STARWARCLOUD STARWAR.AI
返回市场
值搜谷歌搜索-mcp

值搜谷歌搜索-mcp

作者：Incorporo3 星标更新：2025-09-10
安装使用来源：spider==github.com

项目介绍

🔍 ValueSerp MCP Server

<div align="center">

实时集成Google搜索到Claude AI

MCP兼容 Node.js TypeScript npm 版本 许可证: GPL v3

由 ValueSerp API 提供支持 • 使用 Model Context Protocol 构建

</div>

🌟 功能概述

将Claude AI转变为强大的搜索引擎，实时访问Google庞大的知识库。此MCP服务器使Claude能够执行实时Google搜索，浏览新闻，发现图像和视频——所有这些都不离开对话。

✨ 关键亮点

  • 🔍 实时Google搜索 - 实时网页、新闻、图像和视频搜索
  • 🖼️ 智能图像处理 - 自动base64图像检测和本地显示
  • 📊 CSV输出支持 - 结构化数据提取，提供50多个字段选项
  • 🌍 全球定位 - 在任何语言、国家或地区进行搜索
  • ⚡ 高性能 - 使用TypeScript构建，全面错误处理
  • 🔒 生产就绪 - 广泛测试覆盖和安全最佳实践

🛠️ 特性

<table> <tr> <td width="50%">

🔍 搜索工具

  • google_search - 带有AI概述的网络搜索
  • google_news_search - 最新新闻，可排序
  • google_images_search - 带有过滤器的视觉搜索
  • google_videos_search - 视频发现
  • google_places_search - 本地企业和地点发现
  • google_place_details - 关于特定地点的详细信息
</td> <td width="50%">

🎯 高级功能

  • Base64图像处理 - 自动图像提取
  • 综合CSV字段 - 50多个结构化数据字段
  • 地理定位 - 基于位置的结果
  • 时间过滤 - 近期、自定义日期范围
  • 安全搜索 - 内容过滤选项
</td> </tr> </table>

🖼️ 革命性的图像处理

我们的先进图像处理系统自动检测并转换API响应中的base64图像为本地MCP图像资源，提供无缝的视觉体验在Claude中。

特性：

  • ✅ 自动base64检测（PNG、JPEG、GIF、WebP、SVG）
  • ✅ MIME类型识别和验证
  • ✅ 尺寸优化（符合1MB限制）
  • ✅ 循环引用处理
  • ✅ 用户可控的process_images参数

🚀 快速开始

先决条件

# 必需
Node.js 18+
ValueSerp API密钥（免费获取于valueserp.com）

git clone <repository-url>

安装

最简单的方法：使用发布的npm包（推荐）

# 全局安装
npm install -g @incorporo/valueserp-mcp

# 或者直接运行而不安装
npx @incorporo/valueserp-mcp

检查版本：

valueserp-mcp --version  # 输出1.0.0

设置您的API密钥（必需）：

export VALUESERP_API_KEY="your_api_key_here"

然后运行（如果全局安装）：

valueserp-mcp

手动（克隆并构建）

# 1. 克隆仓库
git clone <repository-url>
cd valueserp-mcp

# 2. 安装依赖
npm install

# 3. 构建项目
npm run build

# 4. 设置您的API密钥
export VALUESERP_API_KEY="your_api_key_here"

# 5. 启动服务器
npm start

Claude桌面设置

添加到您的Claude桌面配置中：

📁 配置位置：

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "valueserp": {
      "command": "valueserp-mcp",
      "env": {
        "VALUESERP_API_KEY": "your_api_key_here"
      }
    }
  }
}

📦 发布的包

该服务器已发布到npm作为@incorporo/valueserp-mcp。

名称:     @incorporo/valueserp-mcp
版本:  1.0.0
文件:    dist/*.js + 类型，README，LICENSE
大小:     ~33 kB（压缩）

从您的环境中验证：

npm view @incorporo/valueserp-mcp version

任何时候升级到最新版本：

npm install -g @incorporo/valueserp-mcp@latest

或者无需全局安装即可按需运行：

npx @incorporo/valueserp-m_ cp

🗒️ 更新日志

1.0.0

  • 初始公开发布到npm
  • CLI可执行文件（valueserp-mcp）具有stdio传输
  • 搜索工具：网页、新闻、图像、视频、地点、地点详情
  • 自动base64图像提取到MCP图像块

📖 使用指南

基本网络搜索

{
  "tool": "google_search",
  "parameters": {
    "q": "最新的人工智能发展2025",
    "location": "美国",
    "num": 10,
    "time_period": "last_week",
    "include_ai_overview": true
  }
}

新闻搜索与排序

{
  "tool": "google_news_search", 
  "parameters": {
    "q": "气候变化",
    "sort_by": "date",
    "location": "英国",
    "num": 15,
    "time_period": "last_day"
  }
}

图像搜索与处理

{
  "tool": "google_images_search",
  "parameters": {
    "q": "现代建筑",
    "images_size": "large",
    "images_color": "any",
    "process_images": true,
    "num": 20
  }
}

视频发现

{
  "tool": "google_videos_search",
  "parameters": {
    "q": "TypeScript教程",
    "time_period": "last_month",
    "safe": "active",
    "num": 10
  }
}

地点及本地企业搜索

{
  "tool": "google_places_search",
  "parameters": {
    "q": "咖啡店",
    "location": "旧金山, CA",
    "num": 20,
    "process_images": true
  }
}

地点详情查询

{
  "tool": "google_place_details",
  "parameters": {
    "data_id": "0x87b7122bd8e99a89:0xf20c18461109b2c0",
    "hl": "en",
    "process_images": true
  }
}

⚙️ 配置选项

<details> <summary><b>🔧 完整参数参考</b></summary>

通用参数（所有工具）

参数类型描述示例
q字符串必需。 搜索查询"机器学习"
location字符串地理位置"纽约, NY"
gl字符串国家代码"us"
hl字符串语言代码"en"
num数字每页结果数（1-100）10
page数字页码1
safe字符串安全搜索（active/off）"active"
time_period字符串时间筛选"last_week"
process_images布尔值启用图像处理true

新闻特定参数

参数类型描述
sort_by字符串按相关性或日期排序
show_duplicates布尔值显示重复文章

图像特定参数

参数类型选项
images_color字符串any, black_and_white, transparent, red, blue等。
images_size字符串large, medium, icon
images_type字符串clipart, line_drawing, gif
images_usage字符串使用权限筛选

地点特定参数

参数类型描述
location字符串地点搜索的地理位置。文本位置名称或纬度:经度坐标
num数字地点结果每页数量（最大20）
order_online布尔值返回餐厅的取货/配送信息（成本2个信用）
nfpr数字排除自动更正的结果（1）或包括（0）

地点详情参数

参数类型描述
data_id字符串Google Places数据ID以获取详细信息（更多资料）
data_cid字符串Google Maps数据CID以获取基本信息（有限资料）
hl字符串UI语言代码（默认：en）

注意： 必须提供data_id或data_cid之一（互斥）

</details>

📊 CSV字段及数据结构

丰富的数据提取

每个搜索类型都支持广泛的CSV字段提取用于结构化数据处理：

<details> <summary><b>📈 按搜索类型可用的CSV字段</b></summary>

网络搜索字段

organic_results.position, organic_results.title, organic_results.link, 
organic_results.snippet, organic_results.displayed_link, 
search_information.total_results, related_questions.question, 
knowledge_graph.title, local_results.title, local_results.address

新闻搜索字段

news_results.position, news_results.title, news_results.source,
news_results.date, news_results.link, news_results.snippet,
news_results.thumbnail, search_information.total_results

图像搜索字段

image_results.position, image_results.title, image_results.width,
image_results.height, image_results.image, image_results.link,
image_results.source.name, image_results.description

视频搜索字段

video_results.position, video_results.title, video_results.link,
video_results.length, video_results.source, video_results.date,
video_results.snippet, search_information.total_results

地点搜索字段

places_results.position, places_results.title, places_results.address,
places_results.phone, places_results.rating, places_results.reviews,
places_results.category, places_results.gps_coordinates.latitude,
places_results.gps_coordinates.longitude, local_results.title,
local_results.address, local_results.rating, local_results.reviews

地点详情字段

place_details.title, place_details.type, place_details.address,
place_details.phone, place_details.website, place_details.rating,
place_details.reviews, place_details.description, place_details.hours,
place_details.gps_coordinates.latitude, place_details.gps_coordinates.longitude
</details>

🧪 测试与质量

全面测试套件

# 运行所有测试
npm test

# 运行带有覆盖率
npm run test:coverage

# 运行特定测试套件
npm test tests/unit/
npm test tests/integration/

测试覆盖率：

  • ✅ 56个测试通过 跨单元和集成套件
  • ✅ 6个搜索工具 - 网络、新闻、图像、视频、地点和地点详情
  • ✅ 图像处理 - 24个全面测试
  • ✅ API验证 - 参数验证和错误处理
  • ✅ 集成测试 - 真实场景验证

代码质量

  • 🔍 TypeScript - 完整类型安全和IntelliSense
  • 🛡️ 错误处理 - 优雅的失败恢复
  • 📝 文档 - 综合内联文档
  • 🔒 安全性 - 不硬编码秘密，输入验证

🎯 高级功能

🖼️ Base64图像处理

革命性功能，自动检测API响应中的base64图像，并将其转换为本地MCP图像资源。

{
  "tool": "google_images_search",
  "parameters": {
    "q": "猫",
    "process_images": true    // 启用自动图像处理
  }
}

如何工作：

  1. 🔍 检测 - 扫描API响应中的base64图像数据
  2. 🔄 转换 - 转换为MCP兼容的图像块
  3. 🖼️ 显示 - 图像在Claude界面中本地渲染
  4. ⚡ 优化 - 遵守1MB大小限制以提高性能

🌍 全球定位

在任何语言、国家或地区进行精确定位搜索：

{
  "location": "东京, 日本",
  "gl": "jp",
  "hl": "ja",
  "google_domain": "google.co.jp"
}

🚨 错误处理

服务器提供了全面的错误处理：

  • 🔍 参数验证 - 对无效输入提供清晰的错误消息
  • 🌐 网络弹性 - 自动重试逻辑和超时处理
  • 🔑 API错误翻译 - 人类可读的ValueSerp API错误消息
  • 🛡️ 安全 - 输入净化和速率限制意识

📚 资源

<div align="center">
资源描述
📖 实现指南详细的设置和使用教程
🔧 ValueSerp API 文档完整的API参考
🏗️ MCP协议模型上下文协议规范
💡 获取API密钥免费的ValueSerp API访问
</div>

🤝 贡献

我们欢迎贡献！以下是开始的方法：

# 开发环境设置
git clone <repo-url>
cd valueserp-mcp
npm install
npm run dev

# 运行测试
npm test

# 构建
npm run build

📄 许可证

本项目根据GNU通用公共许可证v3.0发布 - 查看LICENSE文件了解详情。

GPL v3 确保此软件保持免费和开源。任何衍生作品也必须根据GPL v3许可，确保所有用户都能运行、研究、分享和修改软件。

<div align="center">

为Claude AI社区制作 ❤️

为对话式AI带来实时搜索能力

GitHub ValueSerp Claude

</div>