Google Search Console + Claude AI：让 SEO 数据分析对话起来

mcp-gsc 是 Amin Foroutan 开发的一款 Model Context Protocol（MCP）服务器，专门用于将 Google Search Console（GSC）的 SEO 数据接入 Claude、Cursor、Codex CLI 等 AI 助手。它让 SEO 从业者可以用自然语言与自己的网站搜索表现数据对话——"最近哪些页面排名下滑了？""哪些关键词的点击率最高？"——而无需在 GSC 后台和电子表格之间来回切换。

场景切入：SEO 工程师的日常痛点

想象一位独立开发者运营着一个拥有数千篇文章的博客站点。某天，他发现网站流量出现异常波动。按照传统流程，他需要：登录 Google Search Console → 选择站点 → 选择时间范围 → 切换维度（查询/页面/设备/国家）→ 导出数据 → 粘贴到表格 → 筛选对比 → 找出原因。整个过程短则 10 分钟，遇到数据量大的情况甚至需要半小时以上。

mcp-gsc 改变了这个场景。 开发者只需在 Claude Desktop 或 Cursor 中调用 get_search_analytics 工具，几秒钟内就能获得指定时间范围内 Top 20 的热门查询、点击量、展示量、CTR 和平均排名。更进一步，compare_search_periods 工具可以直接对比两个时间段的数据差异，自动标注出下滑最严重的关键词。

技术架构：MCP 协议驱动的模块化设计

mcp-gsc 基于 Model Context Protocol（MCP） 构建。MCP 是 Anthropic 提出的标准化协议，旨在让 AI 助手能够安全、受控地调用外部工具和数据源。与传统的函数调用相比，MCP 提供了更清晰的工具注册、参数校验和结果格式化机制。

项目核心代码集中在单个 gsc_server.py 文件中（约 700 行），架构清晰：

• 认证层：支持两种 Google 认证方式——OAuth 2.0（浏览器交互式登录）和服务账号（JSON 密钥文件）。OAuth 适合个人使用，首次认证后 Token 自动缓存；服务账号适合团队和自动化场景。
• MCP 服务层：使用 FastMCP 库构建，所有工具通过 @mcp.tool() 装饰器注册，支持 stdio 和 SSE 两种传输协议。
• Google API 层：调用 googleapiclient 与 GSC Search Console API v1 交互，支持搜索分析、URL 检查和站点地图三大功能域。

项目依赖极为精简，仅依赖：

• google-api-python-client（GSC API 封装）
• google-auth 系列（Google 身份认证）
• mcp[cli]（MCP 协议支持）
• platformdirs（跨平台配置目录）

不含 LangChain、LlamaIndex 等重型 ML 框架，保持了极低的部署门槛。

核心功能：20+ 工具覆盖 SEO 工作流

mcp-gsc 暴露了约 20 个 MCP 工具，覆盖从认证到数据分析的全流程：

工具分类	代表工具	功能描述
认证	reauthenticate	打开浏览器 OAuth 登录窗口
站点管理	list_properties	列出所有 GSC 站点，获取精确 site_url
搜索分析	get_search_analytics	Top 查询/页面，含点击量、展示量、CTR、排名
对比分析	compare_search_periods	两个时间段的同比/环比数据对比
高级分析	get_advanced_search_analytics	支持过滤、分页、排序，多维度组合
URL 检查	inspect_url_enhanced	单个 URL 的索引状态 + 富媒体结果
批量检查	batch_url_inspection	一次检查最多 10 个 URL（并发）
索引问题	check_indexing_issues	分类汇总索引问题（未收录/规范/robots）
站点地图	get_sitemaps / manage_sitemaps	查看和提交站点地图

特别值得关注的是 batch_url_inspection 和 check_indexing_issues 两个工具的实现细节。前者通过 Python asyncio 并发检查多个 URL，巧妙地使用信号量（Semaphore）控制并发数为 10，规避了 GSC URL Inspection API 每站点每分钟 600 次的限额限制，同时避免了顺序执行超时问题（Issue #31）。后者将检查结果按"未收录/规范问题/robots 屏蔽/抓取问题"四个维度自动分类，极大降低了 SEO 工程师解读结果的认知负担。

容器化部署：Docker + uvx 双路径

mcp-gsc 提供了两种安装路径：

路径一：uvx 一键安装（推荐个人用户）

uvx mcp-search-console

项目注册为 PyPI 包，uvx 自动下载并运行，无需手动配置 Python 环境。首次运行会自动打开浏览器完成 OAuth 认证，之后 Token 持久化到 ~/.config/mcp-gsc/token.json（跨 uvx 版本升级保留认证状态）。

路径二：Docker 容器（适合团队协作）

docker build -t mcp-gsc .
docker run -v /path/to/credentials:/app/credentials mcp-gsc

Dockerfile 基于 ghcr.io/astral-sh/uv:python3.13-bookworm-slim，利用 uv 的层缓存机制优化构建速度。容器默认使用 stdio 传输协议，配置 MCP_TRANSPORT=sse 可切换为 HTTP 模式支持远程/网络部署。

容器部署的关键限制是凭证文件路径。uvx 和 Docker 运行时，代码实际运行在缓存目录而非项目目录，因此凭证文件（如 service_account_credentials.json）必须通过环境变量指定绝对路径：

uvx mcp-search-console   --env GSC_CREDENTIALS_PATH=/absolute/path/to/credentials.json

上手门槛与局限性

mcp-gsc 的上手门槛中等，主要障碍在 Google 侧配置：

1. 必须拥有 GSC 权限：需要有一个已验证所有权的 Google Search Console 属性。
2. Google Cloud 项目配置：OAuth 或服务账号需要关联 Google Cloud 项目，并启用 Search Console API。
3. Python 版本要求：明确要求 Python 3.11+，代码在导入阶段（而非运行时）做版本检查，防止 MCP 客户端静默吞掉报错。

在 Claude Desktop 中配置时，只需在 mcp.json 配置项添加一行：

{
  "mcpServers": {
    "mcp-search-console": {
      "command": "uvx",
      "args": ["mcp-search-console"]
    }
  }
}

局限性方面：项目没有独立的 Web UI，所有交互依赖 AI 助手客户端（Claude Desktop / Cursor / Codex CLI 等）；API 凭证必须手动配置，不支持无凭证的访客模式；搜索分析数据受 GSC API 本身 16 个月回溯限制。

行业意义：AI + SEO 的轻量级融合

mcp-gsc 代表了一个有价值的垂直场景探索——不是用 AI 替代 SEO 工具，而是将 SEO 工具的查询接口自然地嵌入 AI 工作流。在 MCP 协议的支持下，Claude 可以综合网站的 SEO 数据和代码上下文做出更精准的建议（如"根据 GSC 数据，'Python 教程' 页面 CTR 下降了 15%，建议检查是否被新的 SERP 功能覆盖"）。

从 GitHub 数据看，项目 star 数在 MCP 生态中属于中等规模（1700+），但增长轨迹稳健，获得了 Glama.ai、AgenticSkills 等 MCP 目录的收录推荐。开发者社区活跃，已处理多个 PR 合并（安全模式修复、pyproject.toml 打包修复、多传输协议支持等）。

项目 Logo

搜索分析功能示意

技术细节速览

维度	详情
编程语言	Python（需 3.11+）
核心框架	FastMCP（Anthropic MCP）
主要依赖	google-api-python-client, google-auth, mcp[cli]
认证方式	OAuth 2.0 / 服务账号 JSON
传输协议	stdio（默认）/ SSE（HTTP）
安装方式	uvx / pip / Docker
许可证	MIT
Stars	1728（2025年9月）
最新版本	0.4.1