Name: 实时搜索集成服务
Author: Incorporo

使用说明

🔍 ValueSerp MCP服务器

Claude AI的实时谷歌搜索集成

由...驱动 API增值服务 •内置模型上下文协议

🌟 这有什么作用

将Claude AI转化为一个强大的搜索引擎，实时访问谷歌庞大的知识库。此MCP服务器使Claude能够执行实时谷歌搜索、浏览新闻、发现图像和查找视频，而无需离开对话。

✨ 主要亮点

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

🛠️ 特性

🔍 搜索工具

google_search -基于AI概述的网络搜索
google_news_search -分类的最新消息
google_images_search -使用过滤器进行视觉搜索
google_videos_search -视频发现
google_places_search -当地商业和地点发现
google_place_details -具体地点的详细信息

🎯 高性能

Base64图像处理 -自动图像提取
全面的CSV字段 -50+结构化数据字段
地理定位 -基于位置的结果
时间滤波 -最近的自定义日期范围
安全搜索 -内容过滤选项

🖼️ 革命性的图像处理

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

特征：

✅ 自动base64检测（PNG、JPEG、GIF、WebP、SVG）
✅ MIME类型识别和验证
✅ 大小优化（符合1MB限制）
✅ 循环参考处理
✅ 用户可通过以下方式控制 process_images 参数

🚀 快速开始

先决条件

# Required
Node.js 18+
ValueSerp API Key (get free at valueserp.com)

克隆

安装

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

# Install globally
npm install -g @incorporo/valueserp-mcp

# OR run directly without installing
npx @incorporo/valueserp-mcp

检查版本：

valueserp-mcp --version  # prints 1.0.0

设置API密钥（必需）：

export VALUESERP_API_KEY="your_api_key_here"

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

valueserp-mcp

手册（克隆和构建）

# 1. Clone the repository
git clone <repository-url>
cd valueserp-mcp

# 2. Install dependencies
npm install

# 3. Build the project
npm run build

# 4. Set your API key
export VALUESERP_API_KEY="your_api_key_here"

# 5. Start the server
npm start

Claude桌面设置

添加到您的Claude Desktop配置中：

📁 配置位置：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
窗户： %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "valueserp": {
      "command": "valueserp-mcp",
      "env": {
        "VALUESERP_API_KEY": "your_api_key_here"
      }
    }
  }
}

📦 已发布包

服务器发布到npm为 @incorporo/valueserp-mcp.

name:     @incorporo/valueserp-mcp
version:  1.0.0
files:    dist/*.js + types, README, LICENSE
size:     ~33 kB (compressed)

从您的环境中验证：

npm view @incorporo/valueserp-mcp version

随时升级至最新版本：

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

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

npx @incorporo/valueserp-mcp

🗒️ 更新日志

1.0.0

npm首次公开发布
CLI可执行文件(valueserp-mcp)使用stdio传输
搜索工具：网络、新闻、图片、视频、地点、地点详情
MCP图像块的自动base64图像提取

📖 使用指南

基本网络搜索

{
  "tool": "google_search",
  "parameters": {
    "q": "latest AI developments 2025",
    "location": "United States",
    "num": 10,
    "time_period": "last_week",
    "include_ai_overview": true
  }
}

新闻搜索与排序

{
  "tool": "google_news_search", 
  "parameters": {
    "q": "climate change",
    "sort_by": "date",
    "location": "United Kingdom",
    "num": 15,
    "time_period": "last_day"
  }
}

图像搜索与处理

{
  "tool": "google_images_search",
  "parameters": {
    "q": "modern architecture",
    "images_size": "large",
    "images_color": "any",
    "process_images": true,
    "num": 20
  }
}

视频发现

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

地点和当地商业搜索

{
  "tool": "google_places_search",
  "parameters": {
    "q": "coffee shops",
    "location": "San Francisco, CA",
    "num": 20,
    "process_images": true
  }
}

地点详细信息查询

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

⚙️ 配置选项

🔧 Complete Parameter Reference

通用参数（所有工具）

参数	类型	描述	示例
`q`	字符串	必修的。搜索查询	`"machine learning"`
`location`	string	地理位置	`"New York, NY"`
`gl`	string	国家代码	`"us"`
`hl`	string	语言代码	`"en"`
`num`	number	每页结果（1-100）	`10`
`page`	number	页码	`1`
`safe`	string	安全搜索(`active`/`off`)	`"active"`
`time_period`	string	时间过滤器	`"last_week"`
`process_images`	boolean	启用图像处理	`true`

新闻特定参数

参数	类型	说明
`sort_by`	string	排序方式 `relevance` 或 `date`
`show_duplicates`	boolean	显示重复文章

图像特定参数

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

位置特定参数

参数	类型	说明
`location`	string	地点搜索的地理位置。文本位置名称或lat:lon坐标
`num`	number	每页结果的位置数（最多20个）
`order_online`	boolean	返回餐厅的收货/送货信息（花费2个积分）
`nfpr`	number	排除自动更正的结果（1）或包含（0）

地点详细信息参数

参数	类型	说明
`data_id`	string	Google Places数据ID以获取详细信息（更多个人资料数据）
`data_cid`	string	谷歌地图数据CID用于基本信息（有限配置文件）
`hl`	string	UI语言的语言代码（默认值：en）

注：要么 data_id 或 data_cid 必须提供（互斥）

📊 CSV字段和数据结构

丰富的数据提取

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

📈 Available CSV Fields by Search Type

Web搜索字段

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

🧪 测试与质量

综合测试套件

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific test suites
npm test tests/unit/
npm test tests/integration/

测试覆盖范围：

✅ 56项测试通过 跨单元和集成套件
✅ 6搜索工具 -网络、新闻、图片、视频、地点和地点详细信息
✅ 图像处理 -24项综合测试
✅ API验证 -参数验证和错误处理
✅ 集成测试 -真实世界场景验证

代码质量

🔍 TypeScript -全类型安全和智能感知
🛡️ 错误处理 -优雅的故障恢复
📝 文档 -全面的内联文档
🔒 安全 -没有硬编码的秘密，输入验证

🎯 高级功能

🖼️ Base64图像处理

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

{
  "tool": "google_images_search",
  "parameters": {
    "q": "cats",
    "process_images": true    // Enable automatic image processing
  }
}

它是如何工作的：

🔍 检测 -扫描API对base64图像数据的响应
🔄 转换 -转换为MCP兼容的图像块
🖼️ 显示 -图像在Claude界面中以本机方式呈现
⚡ 优化 -尊重1MB的性能大小限制

🌍 全球本土化策略

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

{
  "location": "Tokyo, Japan",
  "gl": "jp",
  "hl": "ja",
  "google_domain": "google.co.jp"
}

🚨 错误处理

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

🔍 参数验证 -清除无效输入的错误消息
🌐 网络弹性 -自动重试逻辑和超时处理
🔑 API错误翻译 -Human-readable ValueSerp API错误消息
🛡️ 安全 -输入净化和限速意识

📚 资源

资源	描述
📖 实施指南	详细的设置和使用教程
🔧 ValueSerp API文件	完整的API参考
🏗️ MCP协议	模型上下文协议规范
💡 获取API密钥	免费访问ValueSerp API

🤝 贡献

我们欢迎捐款！以下是如何开始：

# Development setup
git clone <repo-url>
cd valueserp-mcp
npm install
npm run dev

# Run tests
npm test

# Build
npm run build

📄 许可证

此项目根据GNU通用公共许可证v3.0获得许可-请参阅许可证文件以获取详细信息。

GPL v3 确保该软件保持免费和开源。任何衍生作品也必须根据GPL v3获得许可，保留所有用户运行、研究、共享和修改软件的自由。

由以下材料制成❤️ Claude AI社区

为对话式人工智能带来实时搜索功能