AI导哈

谷歌搜索MCP服务器

一个提供谷歌搜索功能的模型上下文协议（MCP）服务器，具有自动API密钥轮换和智能配额管理功能。

  • by Fabien-desablens
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 Fabien-desablens/google-search-mcp

使用说明

Google Search MCP 服务器

一个模型上下文协议（MCP）服务器，提供带有自动API密钥轮换和智能配额管理的Google搜索功能。

特点/特性

  • 官方Google自定义搜索API集成
  • 自动API密钥轮换以提高每日限额
  • 持续配额追踪 跨会话和目录
  • 多语言和地理定位支持
  • 高级搜索过滤器（日期、文件类型、特定网站）
  • SafeSearch 内容过滤
  • 全局配置 - 从任何地方都能工作
  • 与Claude Desktop及其他MCP客户端兼容

安装

快速设置（推荐）

# Install the package globally
npm install -g @kyaniiii/google-search-mcp

# Run interactive setup
google-search-setup

这将：

  • ✅ 以交互方式配置您的Google API密钥
  • ✅ 设置全局配置文件
  • ✅ 自动与Claude Code集成
  • 每个API密钥每天可进行100多次免费搜索

高级安装

git clone https://github.com/Fabien-desablens/google-search-mcp.git
cd google-search-mcp
npm install
npm run build
npm run setup

卸载

完全移除

# Remove the package
npm uninstall -g @kyaniiii/google-search-mcp

# Remove from Claude Code
claude mcp remove google-search

# Remove configuration file (if desired)
npm run clean

注： 配置文件 (~/.google-search-mcp.json) 是 始终被保存 在更新和卸载过程中保护您的API密钥。使用 npm run clean 只有当你想要完全删除你的配置时。

配置

设置工具创建了一个 全局配置文件 at: （可译为“在”或根据上下文保持原样，若作为独立短语无特定含义时，可不译或译为“（位于）”）

  • Windows： %USERPROFILE%\.google-search-mcp.json
  • Linux/macOS： ~/.google-search-mcp.json

这个文件包含：

  • 您的API密钥和搜索引擎ID
  • ✅ 对号/正确/完成 持续配额跟踪 （存活重启）
  • ✅ 每天午夜（协调世界时）自动重置
  • ✅ 跨目录使用（任何位置均可工作）

示例配置

{
  "keys": [
    {
      "id": "key_1",
      "apiKey": "AIzaSy...",
      "searchEngineId": "abc123...",
      "dailyUsage": 45,
      "dailyLimit": 100,
      "lastReset": "2024-07-30",
      "isActive": true
    }
  ],
  "lastUpdated": "2024-07-30T15:30:00Z",
  "version": "1.0.0"
}

⚠️ 重要提示： 如果你手动编辑配置文件（~/.google-search-mcp.json)，您必须重启 Claude Desktop 才能使更改生效。

获取Google API凭证

1. 创建一个Google云项目

  1. 首选 Google Cloud 控制台
  2. 创建一个新项目或选择现有项目
  3. 启用“自定义搜索API”

2. 生成API密钥

  1. 导航至“APIs 和服务”>“凭据”
  2. 点击“创建凭据”>“API密钥”
  3. 复制生成的密钥

3. 创建自定义搜索引擎

  1. 参观 谷歌可编程搜索引擎
  2. 点击“开始”或“添加”
  3. 对于“搜索的网站”，请输入 * 搜索整个网络
  4. 复制搜索引擎ID

4. 多键缩放

  • 每个Google Cloud项目每天提供100次免费搜索
  • 创建多个项目以获得更多配额（例如，3个项目=每天300次搜索）
  • 服务器会在可用密钥之间自动轮换

与Claude代码的使用

运行安装程序后，服务器将在Claude Code中自动配置。您可以立即使用它：

User: "Search for latest AI news from this week"
Claude: I'll search for the latest AI news using Google Search...

服务器暴露了一个 google_search 具有这些参数的工具：

必需参数

  • query (字符串)：搜索查询

可选参数

  • num (数字)：结果数量（1-10，默认：5）
  • start (数字)：结果的起始索引
  • safe (字符串)：安全搜索级别（'关闭'，'开启'）
  • lr （字符串）：语言限制（例如，'lang_en'，'lang_fr'）
  • gl （字符串）：地理位置（国家代码：'us'（美国），'fr'（法国），'uk'（英国））
  • dateRestrict (字符串)：时间段（'d1'，'w1'，'m1'，'y1'）
  • fileType (字符串)：文件类型过滤器（'pdf'，'doc'，'ppt'）
  • siteSearch (字符串)：搜索特定网站
  • siteSearchFilter (字符串)：包含('i')或排除('e')站点
  • cr (字符串): 国家限制（'countryUS'，'countryFR'）
  • exactTerms （字符串）：要包含的确切短语
  • excludeTerms （字符串）：要排除的术语
  • orTerms (字符串)：备选术语（或搜索）
  • sort (字符串)：按日期排序（'date'）
  • searchType (字符串)：搜索类型（图像搜索时使用 'image'）

示例

基本搜索

{
  "query": "artificial intelligence news"
}

高级搜索

{
  "query": "machine learning",
  "num": 10,
  "lr": "lang_en",
  "gl": "us",
  "dateRestrict": "m1",
  "fileType": "pdf"
}

特定位置搜索

{
  "query": "typescript tutorial",
  "siteSearch": "stackoverflow.com",
  "siteSearchFilter": "i"
}

配额管理

服务器在每次响应中提供实时配额信息：

{
  "results": [...],
  "metadata": {
    "quotaStatus": {
      "totalUsed": 15,
      "totalLimit": 300,
      "keysStatus": [
        {
          "id": "key_1",
          "used": 15,
          "limit": 100,
          "remaining": 85,
          "active": true
        }
      ]
    }
  }
}

配额特性

  • 在UTC时间午夜自动每日重置
  • 达到限制时自动智能更换密钥
  • 禁用的密钥在重置后会自动重新激活
  • 持续追踪 跨服务器重启
  • 无费用 - 遵循免费层级限制

错误处理

服务器优雅地处理各种错误场景：

  • 配额已超出自动旋转到下一个可用键
  • 所有密钥已用尽返回包含配额状态的明确错误信息
  • 无效的API密钥禁用该键并继续处理其他键
  • 网络错误返回详细的错误信息

发展

先决条件

  • Node.js 18及以上版本
  • TypeScript
  • Google Cloud 账户

脚本

# Development mode with auto-reload
npm run dev

# Build for production
npm run build

# Start server
npm start

# Setup configuration
npm run setup

项目结构

google-search-mcp/
├── src/
│   ├── index.ts         # Entry point
│   ├── server.ts        # MCP server setup
│   ├── config.ts        # Configuration wrapper
│   ├── global-config.ts # Global config manager
│   └── tools/
│       └── search.ts    # Search implementation
├── build/               # Compiled JavaScript
├── setup.js             # Interactive setup tool
└── package.json

贡献；做出贡献

欢迎投稿！请：

  1. 为仓库创建分支（或：为仓库进行叉（Fork）操作）
  2. 创建一个特性分支
  3. 做出你的更改
  4. 如适用，请添加测试
  5. 提交拉取请求

许可证

MIT 许可证 - 详见 LICENSE 文件

支持

如需咨询问题、提出疑问或贡献内容，请访问： https://github.com/Fabien-desablens/google-search-mcp 的中文翻译可以是：“GitHub上的Fabien-desablens用户分享的Google搜索MCP项目”。不过，这里的“MCP”可能是一个特定上下文或项目中的缩写，没有具体上下文可能难以准确翻译其含义，但基于常规理解，可以翻译为上述表述。如果“MCP”有特定含义，需要根据具体上下文进行调整

相关 MCP