使用说明

谷歌搜索控制台MCP服务器

一种模型上下文协议（MCP）服务器，提供对Google Search Console数据的只读访问。此服务器部署到Cloudflare Workers，支持两种传输方式：

上海证券交易所 (/sse)--适用于TypingMind和其他使用服务器发送事件的客户端
可流式传输的HTTP (/mcp)--为使用流式HTTP传输（协议版本）的MCP客户端提供直接JSON-RPC POST 2025-03-26)

备注：该项目由承包商规模项目名称中的“cs”后缀指ContractorScale。

特征

12个强大的工具：全面访问Google Search Console数据，分为4层
双重运输上海证券交易所/sse)TypingMind；流式HTTP(/mcp)用于直接JSON-RPC客户端
生产测井：结构化JSON日志通过 wrangler tail 用于请求路由、MCP方法、工具调用、错误和响应
OAuth2身份验证：通过自动刷新实现基于用户令牌的安全身份验证
Cloudflare员工：具有全球边缘网络的无服务器部署
TypeScript：全类型安全和出色的开发人员体验
生产就绪：包括错误处理、CORS、速率限制和会话管理
打字思维兼容：测试并使用TypingMind MCP集成

工具概述

第1层：站点管理（3个工具）

list_sites -列出经过身份验证的用户可访问的所有Google Search Console属性
get_site_details -获取特定Search Console属性的详细信息
search_analytics -通过高级过滤和速赢检测查询全面的搜索性能数据

第2层：URL和网站地图检查（4个工具）

inspect_url -检查特定URL的索引状态和爬网信息
batch_inspect_urls -同时检查多个URL并识别常见模式
list_sitemaps -列出为站点提交的所有站点地图
get_sitemap_details -获取特定站点地图的详细信息

第3层：高级分析（5个工具）

compare_periods -比较两个时间段之间的搜索性能
find_keyword_opportunities -识别速赢关键字机会（位置4-20）
get_device_breakdown -分析不同设备类型（台式机、移动设备、平板电脑）的性能
get_country_breakdown -分析跨地理区域的性能
detect_indexing_issues -检测跨多个URL的索引问题并确定其优先级

快速开始

1.克隆存储库

git clone https://github.com/YOUR_USERNAME/gsc-mcp-cs.git
cd gsc-mcp-cs

2.安装依赖项

npm install

3.设置OAuth2凭据

您需要具有以下范围的Google OAuth2凭据：

https://www.googleapis.com/auth/webmasters.readonly

所需的环境变量：

GOOGLE_CLIENT_ID_TEAM -您的Google OAuth客户端ID
GOOGLE_CLIENT_SECRET_TEAM -您的Google OAuth客户端密钥
GOOGLE_ACCESS_TOKEN -当前访问令牌（将自动刷新）
GOOGLE_REFRESH_TOKEN -刷新令牌以续订令牌

4.配置Cloudflare Workers

复制示例配置：

cp wrangler.jsonc.example wrangler.jsonc

更新 wrangler.jsonc 使用您的设置：

{
	"name": "gsc-mcp-server",
	"main": "src/index.ts",
	"compatibility_date": "2024-01-01",
	"vars": {
		"GOOGLE_CLIENT_ID_TEAM": "your-client-id",
		"GOOGLE_CLIENT_SECRET_TEAM": "your-client-secret"
	},
	"kv_namespaces": [
		{
			"binding": "GSC_TOKENS",
			"id": "your-kv-namespace-id"
		}
	]
}

5.设置Cloudflare Workers KV

创建用于存储OAuth令牌的KV命名空间：

wrangler kv:namespace create GSC_TOKENS

这将输出一个命名空间ID。将其添加到您的 wrangler.jsonc 文件。

6.设定秘密

将敏感值设置为Cloudflare Workers机密：

wrangler secret put GOOGLE_CLIENT_ID_TEAM
wrangler secret put GOOGLE_CLIENT_SECRET_TEAM
wrangler secret put GOOGLE_ACCESS_TOKEN
wrangler secret put GOOGLE_REFRESH_TOKEN

7.本地测试

npm run dev

您的服务器将在 http://localhost:8787

测试运行状况端点：

curl http://localhost:8787

示例响应：

{
  "name": "Google Search Console MCP Server",
  "version": "1.0.0",
  "status": "running",
  "endpoints": {
    "sse": "/sse",
    "mcp": "/mcp"
  }
}

8.部署到Cloudflare Workers

npm run deploy

部署后，Cloudflare将提供您的工作URL（例如。， https://gsc-mcp-server.YOUR_SUBDOMAIN.workers.dev)

使用TypingMind

TypingMind使用SSE传输。这 /mcp 端点是独立的，不影响TypingMind。

将您的MCP服务器部署到Cloudflare Workers
在TypingMind中，转到设置→ MCP服务器
添加新服务器：
- 名称：谷歌搜索控制台MCP服务器
- 统一资源定位符：您的Cloudflare Worker URL（例如。， https://gsc-mcp-server.YOUR_SUBDOMAIN.workers.dev/sse)
- 运输上海证券交易所
- API密钥 （如果已配置）：设置 X-API-Key 标题到你的 API_KEY 秘密
测试连接

与流式HTTP客户端一起使用

支持MCP流式HTTP（协议 2025-03-26)可以直接连接到 POST /mcp 没有SSE会议。每个请求都是一个JSON-RPC消息；响应在HTTP正文中返回。

curl -X POST https://gsc-mcp-server.YOUR_SUBDOMAIN.workers.dev/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}'

POST /mcp 使用与相同的消息处理程序 POST /sse -相同的API密钥验证，相同的工具，相同的JSON-RPC响应。

API终点

方法	路径	描述
`GET`	`/`	运行状况检查（不需要API密钥）。返回服务器名称、版本、状态和可用终结点(`sse`, `mcp`).
`GET`	`/sse`	打开SSE连接；服务器以 `sessionId` 以及消息URL
`POST`	`/sse`	通过HTTP直接JSON-RPC（无SSE会话）
`POST`	`/sse/message?sessionId={id}`	为活动的SSE会话发送JSON-RPC消息
`POST`	`/mcp`	流式HTTP MCP端点——通过HTTP直接JSON-RPC（无SSE会话）

除以下端点外的所有端点 GET / 要求 X-API-Key 标题时 API_KEY 已配置。看发电机_API_KEY.md 用于设置。

生产测井

服务器发出结构化的JSON日志行，旨在 wrangler tail每个日志条目都包含一个时间戳(ts)和a event 用于过滤的名称。

wrangler tail

事件	当它着火时
`request.incoming`	每个请求——方法和路径名
`endpoint.matched`	已选择路由处理程序(`GET /sse`, `POST /mcp`等等）
`auth.failed`	缺失或无效 `X-API-Key`
`mcp.method.parsed`	收到MCP方法(`initialize`, `tools/list`, `tools/call`等等）
`mcp.tools.call`	`tools/call` called--包括工具名称和参数
`mcp.tools.call.error`	工具执行失败--包括错误消息和堆栈跟踪
`mcp.response.sent`	返回给客户端的响应（状态+正文）
`sse.session.created`	新的SSE会议开幕
`sse.response.sent`	响应推送到SSE流
`endpoint.not_found`	不匹配的路线（404）

错误总是包括 error （消息）和 stack （如果可用）用于生产中的调试。

工具文档

第1层：现场管理

`list_sites`

检索经过身份验证的用户有权访问的所有Google Search Console属性。

参数：无

示例响应：

Google Search Console Properties:

You have access to 3 properties:

1. https://example.com/
   Permission: Site Owner
   Type: URL-prefix property

2. sc-domain:example.com
   Permission: Site Owner
   Type: Domain property

3. https://blog.example.com/
   Permission: Full User
   Type: URL-prefix property

Total: 3 properties

`get_site_details`

检索特定Search Console属性的详细信息。

参数：

siteUrl （字符串，必填）：网站URL（例如，“https://example.com/“或”sc域：example.com“）

示例响应：

Site Property Details:

Site URL: https://example.com/
Permission Level: siteOwner
Property Type: URL-prefix property

✓ Access Level: Full Owner - Can manage all aspects

This property is properly configured and accessible.

`search_analytics`

通过高级过滤和速赢检测检索全面的搜索性能数据。

参数：

siteUrl （字符串，必填）：网站URL
startDate （字符串，必填）：YYYY-MM-DD格式的开始日期
endDate （字符串，必填）：YYYY-MM-DD格式的结束日期
dimensions （string[]，可选）：维度数组-有效值：“query”、“page”、“country”、“device”、“searchAppearance”、“date”
type （字符串，可选）：搜索类型-有效值：“web”、“image”、“video”、“news”、“discover”、“googleNews”。默认值：“web”
rowLimit （number，可选）：要返回的最大行数。范围：1-25000。默认值：1000
startRow （数字，可选）：分页的起始行。默认值：0
pageFilter （字符串，可选）：按页面URL过滤。正则表达式模式使用“regex:”前缀
queryFilter （字符串，可选）：按搜索查询筛选。为正则表达式模式使用“regex:”前缀
countryFilter （字符串，可选）：按国家筛选ISO 3166-1 alpha-3代码
deviceFilter （字符串，可选）：按设备类型筛选-有效值：“桌面”、“移动”、“桌面”
detectQuickWins （布尔值，可选）：启用SEO优化机会的自动检测。默认值：false

示例响应：

Search Performance Summary:

Site: https://example.com/
Date Range: 2024-01-01 to 2024-01-31
Dimensions: query, page
Row Limit: 1000 (showing 1000 rows)

Overall Metrics:
- Total Clicks: 12,345
- Total Impressions: 456,789
- Average CTR: 2.70%
- Average Position: 8.5

Performance Indicators:
⚠ Click-through rate is below industry average (5%)
✓ Average position is strong (first page)

Top Performing Queries:
1. "example query"
   Page: https://example.com/page
   Clicks: 1,234 | Impressions: 45,678
   CTR: 2.70% | Position: 3.2

Quick Win Opportunities Detected:
1. "opportunity query" (https://example.com/opportunity)
   Position: 5.2 | Impressions: 2,345
   Current CTR: 1.5%
   → Optimize title tag and meta description to improve CTR

第2层：URL和网站地图检查

`inspect_url`

检索特定URL的详细索引信息。

参数：

siteUrl （字符串，必填）：网站URL属性
inspectionUrl （string，必填）：要检查的完整URL
languageCode （字符串，可选）：响应的语言代码。默认值：“en-US”

示例响应：

URL Inspection Results:

URL: https://example.com/page
Site Property: https://example.com/
Last Crawled: 2024-01-15T10:30:00Z

Index Status:
✓ Overall Verdict: PASS
Coverage State: Submitted and indexed

Crawling & Indexing:
✓ Indexing: Allowed
✓ Robots.txt: Allowed
✓ Page Fetch: Successful

Canonical URLs:
- Google's Canonical: https://example.com/page
- User-Declared Canonical: https://example.com/page
✓ Canonicals match

Mobile Usability:
✓ Passed
No mobile usability issues

Rich Results:
✓ Valid structured data
Detected items:
  - Article
  - BreadcrumbList

✓ This URL is healthy and properly indexed by Google.

`batch_inspect_urls`

一次检查多个URL并识别常见的索引模式。

参数：

siteUrl （字符串，必填）：网站URL属性
urls （string[]，必填）：要检查的URL数组（每次调用最多20个）
languageCode （字符串，可选）：语言代码。默认值：“en-US”

`list_sitemaps`

检索为站点提交的所有站点地图。

参数：

siteUrl （字符串，必填）：网站URL属性
sitemapIndex （字符串，可选）：站点地图索引的URL，用于列出其中的条目

`get_sitemap_details`

检索特定站点地图的详细信息。

参数：

siteUrl （字符串，必填）：网站URL属性
feedpath （string，必填）：站点地图URL（例如，“https://example.com/sitemap.xml")

第3层：高级分析

`compare_periods`

比较两个时间段之间的搜索性能。

参数：

siteUrl （字符串，必填）：网站URL
period1StartDate （字符串，必填）：第一个句点开始（YYYY-MM-DD）
period1EndDate （字符串，必填）：第一个句点结束（YYYY-MM-DD）
period2StartDate （字符串，必填）：第二个句点开始（YYYY-MM-DD）
period2EndDate （字符串，必填）：第二个句点结束（YYYY-MM-DD）
dimensions （string[]，可选）：要比较的尺寸。默认值：[“query”]
metric （字符串，可选）：要比较的度量-有效值：“点击”、“印象”、“ctrl”、“位置”。默认值：“点击”

`find_keyword_opportunities`

识别排名在4-20位的搜索查询，印象高但点击率低。

参数：

siteUrl （字符串，必填）：网站URL
startDate （字符串，必填）：开始日期（YYYY-MM-DD）
endDate （字符串，必填）：结束日期（YYYY-MM-DD）
minPosition （数字，可选）：要考虑的最小位置。默认值：4
maxPosition （数字，可选）：要考虑的最大位置。默认值：20
minImpressions （数字，可选）：最低印象阈值。默认值：100
maxCtr （数字，可选）：要标记的最大CTR百分比。默认值：3

`get_device_breakdown`

分析不同设备类型的搜索性能。

参数：

siteUrl （字符串，必填）：网站URL
startDate （字符串，必填）：开始日期（YYYY-MM-DD）
endDate （字符串，必填）：结束日期（YYYY-MM-DD）
additionalDimension （字符串，可选）：要分解的其他维度（例如，“查询”、“页面”）。默认值：无

`get_country_breakdown`

分析不同国家的搜索性能。

参数：

siteUrl （字符串，必填）：网站URL
startDate （字符串，必填）：开始日期（YYYY-MM-DD）
endDate （字符串，必填）：结束日期（YYYY-MM-DD）
topN （数字，可选）：返回的顶级国家数量。默认值：10
additionalDimension （字符串，可选）：附加维度（例如“query”）。默认值：无

`detect_indexing_issues`

检查多个URL是否存在索引问题，并提供按优先级排列的问题列表。

参数：

siteUrl （字符串，必填）：网站URL
urls （string[]，必填）：要检查的URL数组（最多20个）

示例使用场景

场景1：SEO审计

1. list_sites → Get all properties
2. get_site_details → Verify ownership
3. detect_indexing_issues → Check important pages
4. find_keyword_opportunities → Identify quick wins

场景2：内容性能分析

1. search_analytics → Get last 90 days data
2. compare_periods → Compare with previous 90 days
3. get_device_breakdown → Check mobile vs desktop
4. get_country_breakdown → See geographic distribution

场景3：技术SEO检查

1. list_sitemaps → Review all sitemaps
2. get_sitemap_details → Check for errors
3. batch_inspect_urls → Verify indexing
4. detect_indexing_issues → Prioritize fixes

认证

服务器使用带有用户令牌（而不是服务帐户）的OAuth2。认证流程包括：

令牌存储：OAuth令牌存储在Cloudflare Workers KV中
自动刷新：访问令牌在过期时使用刷新令牌自动刷新
范围: https://www.googleapis.com/auth/webmasters.readonly （只读访问）

获取OAuth2凭据

首选谷歌云控制台
创建新项目或选择现有项目
启用“谷歌搜索控制台API”
创建OAuth 2.0凭据（OAuth客户端ID）
配置OAuth同意屏幕
添加授权重定向URI
下载客户端ID和密码

令牌管理

服务器自动处理令牌刷新。您只需提供：

初始访问令牌
刷新令牌

这些可以通过OAuth2流或现有集成获得。

速率限制

URL检查API：每个酒店约600个电话/分钟
搜索分析API：没有具体限制，但要合理
批量操作：服务器会自动在请求之间添加延迟，以遵守速率限制

响应格式

所有工具都返回人类可读的格式化文本（不是原始JSON），使人工智能助手和用户都能轻松理解响应。答复包括：

清除节标题
格式化数字（例如，“1000”而不是“1000”）
视觉指示器（✓，⚠, ❌, →)
背景和解释
可采取行动的见解和建议

项目结构

.
├── src/
│   └── index.ts          # Main MCP server code
├── test/
│   └── index.spec.ts     # Tests
├── wrangler.jsonc.example  # Example Cloudflare Workers config
├── wrangler.jsonc        # Cloudflare Workers config (gitignored)
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript config
└── README.md             # This file

发展

运行测试

npm test

该项目包括Vitest和Cloudflare Workers测试环境。

类型生成

生成Cloudflare Workers类型：

npm run cf-typegen

故障排除

“找不到工具”错误

确保工具名称完全匹配（区分大小写）
检查工具是否已在中实施 src/index.ts
验证工具是否在工具/列表响应中导出

SSE连接问题

如果从web应用程序连接，请检查CORS标头
验证防火墙没有阻止SSE连接
测试用 curl -N http://localhost:8787/sse 查看原始SSE流

OAuth令牌错误

验证Cloudflare Workers机密中的令牌设置是否正确
检查刷新令牌是否有效且未过期
确保OAuth范围包括 webmasters.readonly
查看Cloudflare Workers日志： wrangler tail （参见生产测井)

401未经授权

确保 X-API-Key 除以下请求外，所有请求都会发送标头 GET /
验证 API_KEY 已设置 wrangler.jsonc vars（本地）或通过 wrangler secret put API_KEY （生产）
检查 auth.failed 事件在 wrangler tail 输出

`/mcp` 客户端连接问题

确认客户端支持MCP协议版本 2025-03-26
使用 POST /mcp 随着 Content-Type: application/json --不是 GET /sse
寻找 mcp.method.parsed 和 mcp.response.sent 事件在 wrangler tail 跟踪请求生命周期

部署失败

确保您已登录Cloudflare： wrangler login
检查wrangler.json中的worker名称是否唯一
验证您的Cloudflare帐户是否启用了Workers
确保KV命名空间已正确创建和绑定

api参考

MCP协议

协议版本: 2025-03-26 （以前 2024-11-05)
运输上海证券交易所/sse, /sse/message)和流式HTTP(/mcp)
文档: 模型上下文协议

谷歌搜索控制台API

API版本：v3（适用于大多数端点），v1（适用于URL检查）
基本URL（v3）: https://www.googleapis.com/webmasters/v3
基本URL（v1）: https://searchconsole.googleapis.com/v1
文档: 谷歌搜索控制台API

使用的关键端点

GET /sites -列出所有网站
GET /sites/{siteUrl} -获取网站详细信息
POST /sites/{siteUrl}/searchAnalytics/query -查询搜索分析
POST /urlInspection/index:inspect -检查URL
GET /sites/{siteUrl}/sitemaps -列出网站地图
GET /sites/{siteUrl}/sitemaps/{feedpath} -获取站点地图详细信息

资源

许可证

麻省理工学院

贡献

欢迎投稿！请打开问题或提交拉取请求。

支持

如果您遇到问题：

检查上面的故障排除部分
查看Cloudflare Workers日志： wrangler tail
在GitHub上打开一个问题：
- 您的wrangler.json（删除敏感数据）
- 日志中的错误消息
- 重现步骤

为TypingMind和其他MCP客户端构建了模型上下文协议（MCP）。

使用说明

谷歌搜索控制台MCP服务器

特征

工具概述

第1层：站点管理（3个工具）

第2层：URL和网站地图检查（4个工具）

第3层：高级分析（5个工具）

快速开始

1.克隆存储库

2.安装依赖项

3.设置OAuth2凭据

4.配置Cloudflare Workers

5.设置Cloudflare Workers KV

6.设定秘密

7.本地测试

8.部署到Cloudflare Workers

使用TypingMind

与流式HTTP客户端一起使用

API终点

生产测井

工具文档

第1层：现场管理

list_sites

get_site_details

search_analytics

第2层：URL和网站地图检查

inspect_url

batch_inspect_urls

list_sitemaps

get_sitemap_details

第3层：高级分析

compare_periods

find_keyword_opportunities

get_device_breakdown

get_country_breakdown

detect_indexing_issues

示例使用场景

场景1：SEO审计

场景2：内容性能分析

场景3：技术SEO检查

认证

获取OAuth2凭据

令牌管理

速率限制

响应格式

项目结构

发展

运行测试

类型生成

故障排除

“找不到工具”错误

SSE连接问题

OAuth令牌错误

401未经授权

/mcp 客户端连接问题

部署失败

api参考

MCP协议

谷歌搜索控制台API

使用的关键端点

资源

许可证

贡献

支持

相关 MCP

文件与终端管理MCP服务

图表生成MCP服务器

ECharts 图表生成 MCP 服务

Excel文件管理分析服务

Elasticsearch/OpenSearch MCP服务器

Metabase MCP 服务器

`list_sites`

`get_site_details`

`search_analytics`

`inspect_url`

`batch_inspect_urls`

`list_sitemaps`

`get_sitemap_details`

`compare_periods`

`find_keyword_opportunities`

`get_device_breakdown`

`get_country_breakdown`

`detect_indexing_issues`

`/mcp` 客户端连接问题