mcp-server-gsc

想象一下，你不需要登录谷歌搜索控制台网页，也不需要手动导出CSV文件，而是在与AI的日常对话中，直接问“上个月有哪些关键词给网站带来了超过100次点击但排名在10-20位之间”，AI就能自动查询并给出答案。这不再是幻想，mcp-server-gsc让这一切成为现实。

mcp-server-gsc是一个模型上下文协议服务器，它将谷歌搜索控制台强大的网站数据能力，通过API无缝接入到你的AI客户端中。无论是了解网站的整体搜索表现，分析具体关键词和页面的点击率，还是发现那些“徘徊在第二页”的潜在优化机会，你的AI都能通过这个服务器，直接、实时地获取最权威的一手数据。

项目基本信息

一、项目介绍

mcp-server-gsc的核心是一个精心设计的MCP工具，它直接调用Google Search Console API，为你提供网站性能数据的访问能力。这个服务器不仅仅是一个数据搬运工，它内置了许多高级分析功能。

它提供的主要工具是search_analytics。通过这个工具，你可以从多个维度分析网站的搜索表现，包括按查询词、页面URL、用户所在国家/地区、使用的设备类型以及搜索外观（如搜索结果是否包含富文本摘要）进行数据分组。

除了基础的数据获取，它还支持强大的过滤功能。你可以使用常规的包含、等于等操作符，甚至可以使用正则表达式来筛选包含特定模式的关键词或页面，例如“找出所有包含‘教程’这个词的查询”。更贴心的是，它内置了一个“快速制胜”检测功能，能自动帮你识别那些有较高展示量、但点击率偏低且排名在4-20位之间的关键词和页面——这些通常是最容易通过优化带来流量提升的机会点。

二、核心优势

深度集成谷歌最权威的网站数据：这是该项目最大的价值所在。谷歌搜索控制台的数据直接来自谷歌搜索引擎，反映了你的网站在谷歌搜索中的真实表现，是任何SEO工作的基石。通过MCP将这一数据源与AI结合，你获得的是一个能直接利用官方、实时、权威数据进行决策的智能顾问。

强大的数据探索能力：它远不止返回一堆枯燥的数字。通过支持多达6个维度（查询词、页面、国家、设备、搜索外观、日期）的组合分析，以及灵活的过滤器和正则表达式，你可以像数据分析师一样深入探索数据。例如，你可以轻松分析“来自美国的移动端用户，在搜索包含‘购买’这个词时，看到的网站哪些页面最多”。

智能的“快速制胜”分析：这个内置功能非常实用，它体现了项目作者对SEO实际工作痛点的理解。它会自动扫描你的搜索数据，找出那些“表现还不错但就差临门一脚”的机会。例如，一个关键词有500次展示，排名在第8位，但点击率很低。这通常意味着优化标题和描述就能带来显著提升。AI可以直接指出这些机会，并给出初步建议。

灵活的部署与使用：作为MCP服务器，它可以通过npx命令直接运行，无需克隆代码。同时，它也提供了完整的Docker支持，以及一个通过Cloudflare Workers部署的远程MCP版本。这意味着无论是个人使用、本地开发还是企业级集成，你都能找到合适的方式。

三、适用场景

场景一：SEO顾问或网站站长的日常数据复盘。每天早上，你可以直接问AI：“昨天整个网站的点击和展示情况如何？相比上周同一天，是增长了还是下降了？”或者“过去28天，带来最多点击的10个页面是哪些？”。AI会从搜索控制台获取数据，并以对话的形式为你呈现一份日报。

场景二：主题性的SEO机会挖掘。当你计划写一篇关于“Rust Web框架”的新文章时，可以问AI：“针对‘Rust Web框架’这个主题，在过去90天里，我的网站有哪些相关的页面被展示了？用户主要搜索了哪些长尾关键词？排名在5-15之间的机会词有哪些？”AI可以帮助你进行系统性的内容缺口分析。

场景三：快速诊断流量波动。当你发现网站流量突然下降时，可以快速提问：“和上周相比，过去三天网站的总点击量变化了多少？是特定设备（如移动端）还是特定国家导致的下滑？” 通过多维度下钻分析，AI能帮你快速定位问题根源。

场景四：自动化SEO报告与警报。你可以结合自动化工具（如GitHub Actions）定期运行这个服务器，让它查询关键指标，然后将结果推送到你的邮箱或即时通讯工具。例如，每天早上8点自动获取“新产生印象的关键词”列表，或当某个核心页面的点击率下降超过20%时，自动发送警报。

四、安装教程

使用这个服务器的前提是你需要拥有一个网站的谷歌搜索控制台管理员权限。请先完成前置认证步骤，再回来配置服务器。

前置步骤：获取谷歌API凭证

1. 访问 Google Cloud Console，创建一个新项目（或选择现有项目）。
2. 在“API和服务”中，搜索并启用 Search Console API。
3. 进入“凭据”页面，点击“创建凭据” > “服务账号”，按指引创建一个服务账号，并选择角色（如“查看者”即可）。
4. 创建完成后，点击该服务账号，进入“密钥”标签，点击“添加密钥” > “创建新密钥”，选择JSON格式。一个包含私钥的JSON文件会自动下载到你的电脑。妥善保管此文件。
5. 最后，关键一步：打开你已经拥有管理员权限的 Google Search Console 网站。点击“设置” > “用户和权限”，点击“添加用户”。在“电子邮件地址”中填入上一步创建的服务账号的邮箱（格式类似your-service-account-name@your-project-id.iam.gserviceaccount.com），权限设为“仅限查看”，然后添加。

第一步：配置MCP客户端

我们以Claude Desktop为例。找到其配置文件：

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

使用文本编辑器打开该文件，添加以下配置。请务必将GOOGLE_APPLICATION_CREDENTIALS的路径改为你刚下载的JSON凭证文件的绝对路径。

{
  "mcpServers": {
    "gsc": {
      "command": "npx",
      "args": ["-y", "mcp-server-gsc"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/完整/路径/到/你的/凭据文件.json"
      }
    }
  }
}

第二步：重启并验证

保存配置文件，然后完全退出你的MCP客户端并重新启动。现在，你可以在对话中尝试提问：“请查询一下我的网站（网址是：你的网站域名）在过去7天的总点击量和展示量。”

如果配置正确，AI会调用search_analytics工具并返回数据。注意，对于刚添加的新网站或新服务账号，数据可能需要一些时间才会出现。

五、使用示例

配置完成后，你就可以像和SEO专家对话一样，用自然语言查询你的网站数据了。AI会自动将你的意图转化为工具调用。

示例一：基础表现查询

提示词：“我的网站是example.com，帮我看看过去28天，按天统计的点击量、展示量和平均点击率。”

AI会调用工具，设置siteUrl: "https://example.com", startDate: "2026-03-30", endDate: "2026-04-26", dimensions: "date"。

示例二：分析关键词和页面

提示词：“针对我的网站example.com，分析一下过去3个月，带来最多点击的前20个关键词，以及它们各自对应的主要页面是哪个。”

AI会使用dimensions: "query,page"和rowLimit: 20，并按点击量降序返回结果。

示例三：使用正则表达式进行高级筛选

提示词：“帮我看看example.com上，所有包含‘how to’或‘tutorial’这两个词的关键词，在过去90天的表现。只要来自移动设备的数据。”

AI会构建一个高级查询，设置queryFilter: "regex:(how to|tutorial)", filterOperator: "includingRegex", deviceFilter: "MOBILE"。

示例四：自动寻找优化机会

提示词：“请对我的网站example.com开启快速制胜检测，找出过去30天内有优化潜力的关键词和页面，位置范围可以放宽到4到20位。”

AI会设置detectQuickWins: true，并可选的quickWinsConfig参数来调整定位范围。它会返回一个专门的分析报告，列出机会点及其指标。

六、常见问题

问题一：服务器提示“未找到凭证”或认证失败。

解决方案：请仔细检查claude_desktop_config.json中GOOGLE_APPLICATION_CREDENTIALS环境变量的路径是否正确，必须是你下载的JSON文件的完整绝对路径。同时，确认该文件没有被移动或删除。另外，请确保在谷歌云控制台正确启用了Search Console API，并且你的服务账号邮箱已经被添加到Search Console的用户列表中。

问题二：查询返回的数据为空或结果很少。

解决方案：这通常是权限问题或数据范围问题。首先，确认你的服务账号对Search Console中的具体网站资源拥有“仅限查看”或更高的权限。其次，Search Console的数据并非实时，通常有2-3天的延迟，查询最近一两天的数据可能为空。最后，确保你查询的siteUrl格式正确，可以是https://example.com/（带斜杠）或sc-domain:example.com（域名级资源）。

问题三：API返回“超过配额”或“速率限制”。

解决方案：谷歌Search Console API有每日使用配额。免费配额是每天查询500次（QPS限制为每分钟5次）。如果你通过AI频繁查询，可能很快耗尽配额。请合理规划查询次数，或者考虑缓存一些基础数据。对于大多数个人网站所有者，这个配额通常足够。

问题四：我想查询超过25000行的数据，怎么办？

解决方案：根据API和项目的限制，单次rowLimit最大为25000。如果你需要更多数据，可以通过调整查询的dimensions或使用startRow参数进行分页。例如，第一次请求rowLimit: 25000，第二次请求时加上startRow: 25000。不过对于大多数分析，前1000行数据已经包含了最有价值的信息。

问题五：我看到了“快速制胜检测”功能，但它的推荐准确吗？

解决方案：这个功能基于通用的SEO逻辑：排名在4-20位、有足够展示量但点击率偏低的词最有优化价值。它提供的列表是一个很好的起点，但你需要结合自己的业务知识进行判断。例如，一个排名第5但点击率已经10%的关键词，可能已经表现很好了。建议将AI的“快赢”建议作为线索，而不是最终指令。

七、总结

mcp-server-gsc是一个将专业SEO数据与通用AI能力相结合的杰出范例。它精准地解决了网站所有者、博主和SEO从业者的一个核心痛点：如何高效、及时地利用搜索控制台的海量数据做决策。

这个项目的强大之处在于，它不仅提供了数据访问，还通过支持正则表达式、多维度交叉分析和智能机会检测，将数据查询提升到了数据洞察的层面。当你将谷歌最权威的数据源与AI强大的自然语言交互和推理能力结合时，产生的价值是巨大的。你不再需要成为一个复杂的电子表格高手，只需要像聊天一样，就能完成深入的网站分析。

它的使用门槛主要在于前期的谷歌API认证配置，这对于不熟悉云服务控制台的普通用户来说可能需要花费一些时间。但一旦配置完成，它就能为你持续地、高效地工作。

如果你是一个网站的管理者，或者对SEO数据分析感兴趣，我强烈推荐你投入一点时间尝试mcp-server-gsc。它将彻底改变你与网站搜索数据互动的方式。