Google Custom Search MCP

Google Custom Search MCP 服务

一个异步 Python MCP（Model Context Protocol）服务，通过服务账号身份验证提供对 Google Custom Search API 的访问。

功能

• google_search：执行 Google Custom Search 查询，并可配置结果数量
• 服务账号身份验证：使用 Google 服务账号身份验证（由于 API 密钥已弃用，因此必须使用此方式）
• 双重身份验证支持：本地开发使用文件路径，CI/CD 使用 base64
• 实时集成测试：针对 Google Custom Search API 执行真实测试
• FastMCP 集成：使用最新的 FastMCP Python SDK
• Docker 支持：基于 Alpine Linux 的 Docker 映像，体积小巧
• UV 兼容性：使用 UV 进行现代 Python 打包

快速开始

前置条件

1. Google 服务账号：在 Google Cloud Console 中创建服务账号
2. Custom Search Engine ID：在 Programmable Search Engine 中创建 Custom Search Engine
3. 启用 Custom Search API：为你的 Google Cloud 项目启用该 API

安装

# Clone the repository
git clone <your-repo-url>
cd google-custom-search-mcp

# Install with UV
uv sync

# Set environment variables
export GOOGLE_SERVICE_ACCOUNT_FILE=/path/to/your/service-account-key.json
export GOOGLE_SEARCH_ENGINE_ID=your-search-engine-id

# Run the server
uv run google-custom-search-mcp

用于 CI/CD（base64 编码的服务账号）

# Encode your service account JSON file to base64
base64 -i your-service-account-key.json -w 0 > service-account-base64.txt

# Use base64 encoded credential
export GOOGLE_SERVICE_ACCOUNT_BASE64=$(cat service-account-base64.txt)
export GOOGLE_SEARCH_ENGINE_ID=your-search-engine-id

# Run the server
uv run google-custom-search-mcp

使用 Claude CLI 快速设置

# Using file path (local development)
claude mcp add google-custom-search \
  -s user \
  uv run google-custom-search-mcp \
  -e GOOGLE_SERVICE_ACCOUNT_FILE=/path/to/service-account-key.json \
  -e GOOGLE_SEARCH_ENGINE_ID=your-search-engine-id

# Using base64 (CI/CD)
claude mcp add google-custom-search \
  -s user \
  uv run google-custom-search-mcp \
  -e GOOGLE_SERVICE_ACCOUNT_BASE64=your-base64-encoded-json \
  -e GOOGLE_SEARCH_ENGINE_ID=your-search-engine-id

Claude Desktop 设置（手动）

将以下内容添加到 Claude Desktop 配置中：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "google-custom-search": {
      "command": "uv",
      "args": ["run", "google-custom-search-mcp"],
      "env": {
        "GOOGLE_SERVICE_ACCOUNT_FILE": "/path/to/your/service-account-key.json",
        "GOOGLE_SEARCH_ENGINE_ID": "your-search-engine-id"
      }
    }
  }
}

CLI 用法

该服务支持不同的传输模式：

STDIO 模式（默认）

用于 Claude Desktop 或命令行交互：

python server.py  # Uses STDIO transport by default

HTTP 模式

用于在容器中部署或作为 Web 服务运行：

python server.py --transport http --host 0.0.0.0 --port 3000

CLI 参数

• --transport：传输模式（stdio 或 http，默认值：stdio）
• --host：要绑定的 HTTP 主机（默认值：0.0.0.0）
• --port：要监听的 HTTP 端口（默认值：3000）

示例

# Run in STDIO mode (for Claude Desktop)
python server.py

# Run as HTTP server on default port
python server.py --transport http

# Run on custom port
python server.py --transport http --port 8080

# Run on specific interface
python server.py --transport http --host 127.0.0.1 --port 5000

设置 Google 服务账号

1. 创建 Google Cloud 项目

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

2. 创建服务账号

1. 前往“IAM & Admin”>“Service Accounts”
2. 点击“Create Service Account”
3. 填写名称和说明
4. 授予相应角色（Custom Search API 需要 CSE 角色）
5. 点击“Create Key”并下载 JSON 密钥文件

3. 创建 Custom Search Engine

1. 前往 Programmable Search Engine
2. 点击“Add”创建新的搜索引擎
3. 配置搜索偏好设置
4. 从控制面板获取 Search Engine ID

4. 设置环境变量

本地开发（文件路径）：

export GOOGLE_SERVICE_ACCOUNT_FILE=/path/to/your/service-account-key.json
export GOOGLE_SEARCH_ENGINE_ID=your_actual_search_engine_id_here

CI/CD（base64 编码）：

# Encode service account JSON to base64
base64 -i your-service-account-key.json -w 0 > service-account-base64.txt

export GOOGLE_SERVICE_ACCOUNT_BASE64=$(cat service-account-base64.txt)
export GOOGLE_SEARCH_ENGINE_ID=your_actual_search_engine_id_here

可用函数

Google Search

google_search({
  query: "Your search query",
  num_results?: 10  # Optional, 1-100 (default: 10)
})

响应格式：

{
  "results": [
    {
      "title": "Result Title",
      "link": "https://example.com",
      "snippet": "Result description...",
      "display_link": "example.com"
    }
  ],
  "total_results": 100,
  "search_time": 0.5
}

Docker 用法

Docker 映像默认在端口 3000 上以 HTTP 模式运行。

构建映像

docker build -t google-custom-search-mcp .

运行容器

容器默认在端口 3000 上以 HTTP 模式运行：

# Using file mount
docker run -d \
  -p 3000:3000 \
  -v /path/to/service-account-key.json:/app/service-account-key.json \
  -e GOOGLE_SERVICE_ACCOUNT_FILE=/app/service-account-key.json \
  -e GOOGLE_SEARCH_ENGINE_ID=your-engine-id \
  google-custom-search-mcp

# Using base64 environment variable (recommended for production)
docker run -d \
  -p 3000:3000 \
  -e GOOGLE_SERVICE_ACCOUNT_BASE64=your-base64-encoded-json \
  -e GOOGLE_SEARCH_ENGINE_ID=your-engine-id \
  google-custom-search-mcp

MCP 客户端可通过 http://localhost:3000 访问该服务。

使用 Helm 在 Kubernetes 上部署

Helm chart 可帮助你轻松地将 MCP 服务部署到 Kubernetes。

快速安装

# Clone the repository
git clone https://github.com/fbettag/google-custom-search-mcp.git
cd google-custom-search-mcp

# Install using Helm
helm install google-custom-search-mcp ./charts/google-custom-search-mcp \
  --set google.searchEngineId="your-search-engine-id" \
  --set serviceAccount.base64.value="$(base64 -w 0 < your-service-account.json)" \
  --set serviceAccount.base64.enabled=true

升级部署

helm upgrade google-custom-search-mcp ./charts/google-custom-search-mcp \
  --set google.searchEngineId="your-search-engine-id" \
  --set serviceAccount.base64.value="$(base64 -w 0 < your-service-account.json)" \
  --set serviceAccount.base64.enabled=true

卸载

helm uninstall google-custom-search-mcp

使用 Values 文件

创建一个 values-prod.yaml 文件：

# values-prod.yaml
replicaCount: 2

google:
  searchEngineId: "your-search-engine-id"

serviceAccount:
  base64:
    enabled: true
    value: "your-base64-encoded-service-account-json"

resources:
  requests:
    memory: "128Mi"
    cpu: "100m"
  limits:
    memory: "256Mi"
    cpu: "200m"

使用 Values 文件安装：

helm install google-custom-search-mcp . -f values-prod.yaml

升级现有部署

helm upgrade google-custom-search-mcp . \
  --set google.searchEngineId="your-search-engine-id" \
  --set serviceAccount.base64.value="$(base64 -i your-service-account.json -w 0)"

卸载

helm uninstall google-custom-search-mcp

图表配置

Helm 图表支持各种配置选项：

参数	描述	默认值
replicaCount	副本数量	1
image.repository	Docker 镜像仓库	your-username/google-custom-search-mcp
image.tag	Docker 镜像标签	latest
google.searchEngineId	Google Custom Search Engine ID	""
serviceAccount.base64.enabled	使用 Base64 编码的服务账号	true
serviceAccount.base64.value	Base64 编码的服务账号 JSON	""
serviceAccount.existingFile.enabled	使用服务账号文件挂载	false
serviceAccount.existingFile.path	服务账号文件路径	""
service.type	Kubernetes 服务类型	ClusterIP
service.port	服务端口	3000
resources.requests	资源请求	memory: 64Mi, cpu: 50m
resources.limits	资源限制	memory: 128Mi, cpu: 100m

GitHub CI/CD 设置

仓库机密

将以下机密添加到 GitHub 仓库：

1. GOOGLE_SERVICE_ACCOUNT_BASE64：Base64 编码的服务账号 JSON 文件
2. GOOGLE_SEARCH_ENGINE_ID：你的 Custom Search Engine ID

为 GitHub 编码服务账号

# Encode service account JSON to base64 (no line wraps)
base64 -i your-service-account-key.json -w 0

# Copy the output and add as GitHub secret GOOGLE_SERVICE_ACCOUNT_BASE64

开发

设置开发环境

# Clone and setup
uv sync --dev

# Run live integration tests (requires valid credentials)
uv run pytest tests/ -v

# Run with coverage
uv run pytest tests/ --cov=server --cov-report=html

# Linting
uv run ruff check .
uv run ruff format .

# Type checking
uv run mypy server.py

测试

测试会使用实际的 Google Custom Search API 执行实时集成测试。你必须设置：

export GOOGLE_SERVICE_ACCOUNT_BASE64=your-base64-encoded-json
export GOOGLE_SEARCH_ENGINE_ID=your-search-engine-id

环境变量

变量	描述	必需
GOOGLE_SERVICE_ACCOUNT_FILE	服务账号 JSON 文件路径	此项或 Base64 编码二选一
GOOGLE_SERVICE_ACCOUNT_BASE64	Base64 编码的服务账号 JSON	此项或文件路径二选一
GOOGLE_SEARCH_ENGINE_ID	Custom Search Engine ID	是

API 限额和定价

• Google Custom Search API 每天免费提供 100 次搜索查询
• 更多查询需要设置结算
• 服务账号的配额限制与用户账号相同
• 请参阅 Google Custom Search 定价

贡献

1. Fork 此仓库
2. 创建功能分支：git checkout -b feature/amazing-feature
3. 提交更改：git commit -m 'Add amazing feature'
4. 推送到分支：git push origin feature/amazing-feature
5. 创建 Pull Request

许可证

MIT 许可证——详情请参阅 LICENSE 文件。

支持

如有问题或疑问：

1. 查看 Google Custom Search 文档
2. 查看现有的 GitHub 问题
3. 创建新问题并提供详细信息