Valueserp Mcp - Affordable Google Searches

🔍 ValueSerp MCP 服务

🌟 功能介绍

将 Claude AI 转变为强大的搜索引擎，实时访问 Google 庞大的知识库。此 MCP 服务让 Claude 无需离开对话，即可执行实时 Google 搜索、浏览新闻、发现图片和查找视频。

✨ 主要亮点

• 🔍 实时 Google 搜索 - 实时搜索网页、新闻、图片和视频
• 🖼️ 智能图片处理 - 自动检测 base64 图片并原生显示
• 📊 支持 CSV 输出 - 提取结构化数据，提供 50 多种字段选项
• 🌍 全球本地化 - 使用任意语言、国家或地区进行搜索
• ⚡ 高性能 - 使用 TypeScript 构建，具备全面的错误处理
• 🔒 可用于生产环境 - 测试覆盖全面，并遵循安全最佳实践

🛠️ 功能

🖼️ 革新性的图片处理

我们的高级图片处理系统会自动检测 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)

git clone

安装

最简单的方法：使用已发布的 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 Desktop 设置

添加到 Claude Desktop 配置中：

📁 配置位置：

• 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。

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 上首次公开发布
• 提供带有 stdio 传输的 CLI 可执行文件（valueserp-mcp）
• 搜索工具：网页、新闻、图片、视频、地点和地点详情
• 自动将 base64 图片提取为 MCP 图片块

📖 使用指南

基本网页搜索

{
  "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
  }
}

⚙️ 配置选项

📊 CSV 字段和数据结构

丰富的数据提取

每种搜索类型都支持提取大量 CSV 字段，以便处理结构化数据：

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——完整的类型安全和 IntelliSense
• 🛡️ 错误处理——优雅地从故障中恢复
• 📝 文档——全面的内联文档
• 🔒 安全性——不硬编码机密信息，并进行输入验证

🎯 高级功能

🖼️ Base64 图像处理

这项创新功能可自动检测 API 响应中的 Base64 图像，并将其转换为原生 MCP 图像资源。

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

工作原理：

1. 🔍 检测——扫描 API 响应，查找 Base64 图像数据
2. 🔄 转换——转换为兼容 MCP 的图像块
3. 🖼️ 显示——图像可在 Claude 界面中原生呈现
4. ⚡ 优化——遵循 1MB 大小限制，确保性能

🌍 全球本地化

使用精准定位，以任意语言搜索任何国家或地区：

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

🚨 错误处理

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

• 🔍 参数验证——为无效输入提供清晰的错误消息
• 🌐 网络韧性——自动重试逻辑和超时处理
• 🔑 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 General Public License v3.0 许可，详情请参阅 LICENSE 文件。

GPL v3 确保本软件始终免费且开源。任何衍生作品也必须采用 GPL v3 许可，从而保障所有用户运行、研究、分享和修改软件的自由。