使用说明

谷歌自定义搜索MCP服务器

一个异步Python MCP（模型上下文协议）服务器，使用服务帐户身份验证提供对Google自定义搜索API的访问。

特性

谷歌搜索：使用可配置的结果计数执行Google自定义搜索查询
服务帐户身份验证：使用Google服务帐户身份验证（由于不赞成使用API密钥，因此需要）
双重身份验证支持：本地开发的文件路径，CI/CD的base64
实时集成测试：针对Google Custom Search API的真实测试
FastMCP集成：使用最新的FastMCP Python SDK
Docker支持：基于Alpine Linux的Docker镜像，占用空间最小
紫外线兼容性：带UV的现代Python打包

快速开始

先决条件

Google服务帐户：在中创建服务帐户谷歌云控制台
自定义搜索引擎ID：在以下位置创建自定义搜索引擎可编程搜索引擎
启用自定义搜索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桌面设置（手动）

添加到您的Claude Desktop配置中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
视窗: %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.创建谷歌云项目

首选谷歌云控制台
创建新项目或选择现有项目
启用自定义搜索API

2.创建服务帐户

导航到“IAM&Admin”>“服务帐户”
点击“创建服务帐户”
填写姓名和描述
授予适当的角色（自定义搜索API需要CSE角色）
点击“创建密钥”并下载JSON密钥文件

3.创建自定义搜索引擎

首选可编程搜索引擎
点击“添加”以创建新的搜索引擎
配置您的搜索首选项
从控制面板获取搜索引擎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({
  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

服务器将在以下时间可用 http://localhost:3000 对于MCP客户。

使用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-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"

使用值文件安装：

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 chart支持多种配置选项：

参数	说明	默认值
`replicaCount`	副本数量	`1`
`image.repository`	Docker镜像仓库	`your-username/google-custom-search-mcp`
`image.tag`	Docker镜像标签	`latest`
`google.searchEngineId`	谷歌自定义搜索引擎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存储库中：

GOOGLE_SERVICE_ACCOUNT_BASE64：Base64编码的服务帐户JSON文件
GOOGLE_SEARCH_ENGINE_ID：您的自定义搜索引擎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

测试

测试执行 实时集成测试 与实际的谷歌自定义搜索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`	自定义搜索引擎ID	是

API限制和定价

谷歌自定义搜索API每天免费提供100个搜索查询
其他查询需要计费设置
服务帐户的配额限制与用户帐户相同
参见谷歌自定义搜索定价

贡献

分叉存储库
创建要素分支： git checkout -b feature/amazing-feature
提交更改： git commit -m 'Add amazing feature'
推送到分支： git push origin feature/amazing-feature
打开拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

支持

对于问题和疑问：

检查 Google自定义搜索文档
查看现有的GitHub问题
创建包含详细信息的新问题