Google Search Mcp

Google Search MCP Server

一种提供 Google 搜索功能的 Model Context Protocol（MCP）服务器，支持自动轮换 API 密钥和智能配额管理。

功能

• 集成官方 Google Custom Search 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。

配置

设置工具会在以下位置创建一个全局配置文件：

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

此文件包含：

• ✅ 你的 API 密钥和搜索引擎 ID
• ✅ 持久跟踪配额（重启后仍然保留）
• ✅ 每天 UTC 午夜自动重置
• ✅ 跨目录使用（可在任何位置使用）

配置示例

{
  "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 Cloud 项目

1. 前往 Google Cloud Console
2. 创建新项目或选择现有项目
3. 启用“Custom Search API”

2. 生成 API 密钥

1. 前往“APIs & Services” > “Credentials”
2. 点击“Create Credentials” > “API Key”
3. 复制生成的密钥

3. 创建 Custom Search Engine

1. 访问 Google Programmable Search Engine
2. 点击“Get started”或“Add”
3. 在“Sites to search”中输入 *，以搜索整个网络
4. 复制搜索引擎 ID

4. 使用多个密钥扩展配额

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

在 Claude Code 中使用

运行设置后，服务器会自动配置到 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（字符串）：SafeSearch 级别（'off'、'active'）
• 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（字符串）：替代词语（OR 搜索）
• 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