MCP Google Search Console

mcp-google-search-console-crunchtools

用于 Google Search Console 的安全 MCP 服务。查询搜索分析数据（点击次数、展示次数、点击率、排名），管理站点地图，检查 URL 索引状态，并管理站点属性。

安装

uvx（推荐，无需安装）

claude mcp add mcp-google-search-console-crunchtools \
    --env GSC_CLIENT_ID=your_client_id \
    --env GSC_CLIENT_SECRET=your_client_secret \
    --env GSC_REFRESH_TOKEN=your_refresh_token \
    -- uvx mcp-google-search-console-crunchtools

pip

pip install mcp-google-search-console-crunchtools

容器（Podman/Docker）

podman run -d -p 8017:8017 \
    --env-file ~/.config/mcp-env/mcp-google-search-console.env \
    quay.io/crunchtools/mcp-google-search-console \
    --transport streamable-http --host 0.0.0.0

OAuth 设置

此服务支持两种身份验证方式：基于浏览器的 OAuth（推荐）和环境变量（备用）。

选项 A：基于浏览器的 OAuth（推荐）

基于浏览器的 OAuth 会自动处理令牌交换。凭据过期时，访问 /auth URL 并点击 Google 的授权同意页面即可，无需手动交换代码。

第 1 步：创建 Google Cloud OAuth 应用

1. 前往 Google Cloud Console
2. 创建新项目（或选择现有项目）
3. 前往 APIs & Services > Library
4. 搜索 Google Search Console API 并点击 Enable
5. 前往 APIs & Services > Credentials
6. 点击 + CREATE CREDENTIALS > OAuth client ID
7. 如果出现提示，请先配置 OAuth 授权同意页面：
   • 用户类型：External（如果使用 Google Workspace，也可以选择 Internal）
   • 应用名称：任意名称（例如，“MCP Search Console”）
   • 范围：添加 https://www.googleapis.com/auth/webmasters
   • 测试用户：添加你的 Google 账号邮箱
8. 返回“Create OAuth client ID”页面：
   • 应用类型：Web application
   • 名称：任意名称（例如，“MCP Search Console”）
   • 已授权的重定向 URI：添加服务的回调 URL（例如，https://mcp-gsc.example.com/oauth2callback）
9. 点击 Create — 复制 Client ID 和 Client Secret

第 2 步：配置并启动

创建 env 文件：

cat > ~/.config/mcp-env/mcp-google-search-console.env << 'EOF'
GSC_CLIENT_ID=your_client_id
GSC_CLIENT_SECRET=your_client_secret
GSC_CREDENTIALS_DIR=/data
GSC_OAUTH_REDIRECT_URI=https://mcp-gsc.example.com/oauth2callback
EOF
chmod 600 ~/.config/mcp-env/mcp-google-search-console.env

启动服务，并为凭据配置持久化卷：

podman run -d -p 8017:8017 \
    --env-file ~/.config/mcp-env/mcp-google-search-console.env \
    -v mcp-gsc-data:/data:Z \
    quay.io/crunchtools/mcp-google-search-console \
    --transport streamable-http --host 0.0.0.0

第 3 步：进行身份验证

在浏览器中访问 https://mcp-gsc.example.com/auth。你会被重定向到 Google 的授权同意页面。授予访问权限后，服务会自动保存凭据。

令牌过期时，任何工具调用都会返回 /auth URL。点击该链接即可重新进行身份验证，无需重启容器。

选项 B：环境变量（备用）

如果你倾向于使用静态凭据，或无法公开回调 URL，请在 env 文件中设置 GSC_REFRESH_TOKEN。请参阅下文的手动 OAuth 流程。

export GSC_CLIENT_ID="your_client_id_here"
export GSC_CLIENT_SECRET="your_client_secret_here"

echo "https://accounts.google.com/o/oauth2/v2/auth?client_id=${GSC_CLIENT_ID}&redirect_uri=http://127.0.0.1&response_type=code&scope=https://www.googleapis.com/auth/webmasters&access_type=offline&prompt=consent"

curl -s -X POST https://oauth2.googleapis.com/token \
    -d "client_id=${GSC_CLIENT_ID}" \
    -d "client_secret=${GSC_CLIENT_SECRET}" \
    -d "code=PASTE_CODE_HERE" \
    -d "grant_type=authorization_code" \
    -d "redirect_uri=http://127.0.0.1" | python3 -m json.tool

运行时工作原理

服务会按以下顺序检查凭据：

1. 来自 GSC_CREDENTIALS_DIR/credentials.json 的文件凭据（由基于浏览器的流程写入）
2. 环境变量 GSC_REFRESH_TOKEN（备用）

每次 API 调用时，服务都会将刷新令牌交换为短期访问令牌（约 1 小时），并将其缓存在内存中，自动刷新。更新后的令牌会持久化到凭据文件中，以便在容器重启后继续使用。

可用工具（10 个）

安全性

• OAuth2 凭据以 SecretStr 存储（绝不记录到日志中）
• 基于文件的凭据以 0o600 权限写入（原子写入）
• 自动从错误消息中清除令牌
• 使用 Pydantic 验证输入，并设置 extra="forbid"
• 不访问文件系统、不执行 shell 命令，也不求值代码
• 验证 TLS 证书（httpx 默认行为）
• 设置请求超时和响应大小限制
• 基于 Hummingbird 容器镜像构建

完整的安全设计文档请参阅 SECURITY.md。

开发

uv sync --all-extras
uv run ruff check src tests
uv run mypy src
uv run pytest -v
gourmand --full .
podman build -f Containerfile .

许可证

AGPL-3.0-or-later