谷歌搜索控制台MCP服务器
一种模型上下文协议（MCP）服务器，为LLM提供对Google Search Console数据和功能的编程访问。内置于 FastMCP.
特性
🛠️ 工具（13个动作）
搜索分析
query_search_analytics-使用过滤器和维度查询搜索流量数据
网站地图管理
list_sitemaps-列出站点的所有站点地图get_sitemap-获取特定站点地图的详细信息submit_sitemap-向谷歌提交网站地图delete_sitemap-删除站点地图
站点管理
list_sites-列出您的Search Console帐户中的所有站点get_site-获取特定网站的信息add_site-将网站添加到搜索控制台delete_site-从Search Console中删除网站
URL检查
inspect_url-检查特定URL的Google索引状态
📊 资源（6个数据源）
gsc://sites-列出所有可用网站gsc://config-服务器配置和状态gsc://sites/{site_url}/analytics/summary-最近分析摘要（28天）gsc://sites/{site_url}/sitemaps-网站地图gsc://sites/{site_url}/top-queries-前10个查询（7天）gsc://sites/{site_url}/top-pages-前10页（7天）
💬 提示（4个模板）
analyze_search_performance-生成SEO性能分析提示seo_recommendations-生成SEO建议提示compare_periods-生成期间比较提示indexing_health_check-生成索引健康检查提示
安装
先决条件
- Python 3.10或更高版本
- 启用搜索控制台API的谷歌云项目
- 来自谷歌云控制台的OAuth 2.0凭据
再进行
# Clone the repository
git clone https://github.com/damupi/mcp-gsc.git
cd mcp-gsc
# Install with uv (recommended)
uv sync
# Or install in development mode
uv pip install -e .身份验证设置
此服务器使用 FastMCP内置的Google OAuth集成.
步骤1：创建Google OAuth 2.0凭据
- 首选 谷歌云控制台
- 创建新项目或选择现有项目
- 启用 谷歌搜索控制台API
- 首选 凭证 → 创建凭据 → OAuth 2.0客户端ID
- 在系统提示时配置OAuth同意屏幕
- 选择 Web应用程序 作为应用程序类型
- 添加授权的Javascript源代码：
http://localhost - 添加授权重定向URI：
http://localhost:8000/auth/callback - 保存您的 客户端ID 和 客户端密钥
步骤2：配置环境变量
创建一个 .env 项目根目录中的文件：
cp .env.example .env编辑 .env 并添加您的凭据：
FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.google.GoogleProvider
FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_SECRET=GOCSPX-your-client-secret
FASTMCP_SERVER_AUTH_GOOGLE_REQUIRED_SCOPES=openid,https://www.googleapis.com/auth/userinfo.email,https://www.googleapis.com/auth/webmasters用法
运行服务器
开发模式（STDIO）
fastmcp dev src/mcp_gsc/server.py生产模式（HTTP传输）
# Run with HTTP transport for remote access
fastmcp run src/mcp_gsc/server.py --transport http
# Specify custom host and port
fastmcp run src/mcp_gsc/server.py --transport http --host 0.0.0.0 --port 8080服务器将于启动 http://localhost:8000 默认情况下（HTTP模式）。
使用Docker运行
快速入门：
# Build the Docker image
make build
# Start the server
make up
# View logs
make logs
# Stop the server
make down可用的生成命令：
make build-构建Docker镜像make up-在后台启动MCP服务器make down-停止MCP服务器make restart-重新启动服务器make logs-查看服务器日志（跟踪模式）make logs-tail-查看最后100行日志make status-检查服务器状态make clean-删除所有Docker资源make shell-在运行容器中打开一个shellmake rebuild-重建并重新启动make dev-使用实时日志运行make test-测试服务器运行状况端点
Docker配置：
服务器在Docker容器中运行：
- Python 3.12精简基础镜像
- UV用于快速依赖管理
- 端口8000上的HTTP传输
- 故障时自动重启
- 每30秒进行一次健康检查
确保你的 .env 文件在运行前已配置 make up.
身份验证流程
- 启动服务器
- 连接MCP客户端（例如Claude Desktop）
- 您将被重定向到Google OAuth登录
- 授予访问Search Console数据的权限
- 您将被重定向并通过身份验证
与Claude Desktop一起使用
选项1:STDIO传输（本地）
添加到您的Claude Desktop配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：
{
"mcpServers": {
"gsc-mcp-server": {
"command": "fastmcp",
"args": ["run", "src/mcp_gsc/server.py"],
"env": {
"FASTMCP_SERVER_AUTH": "fastmcp.server.auth.providers.google.GoogleProvider",
"FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
"FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_SECRET": "GOCSPX-your-client-secret",
"FASTMCP_SERVER_AUTH_GOOGLE_REQUIRED_SCOPES": "openid,https://www.googleapis.com/auth/userinfo.email,https://www.googleapis.com/auth/webmasters"
}
}
}
}选项2:HTTP传输（远程）
首先，使用HTTP传输启动服务器：
fastmcp run src/mcp_gsc/server.py --transport http然后配置Claude Desktop通过HTTP连接：
{
"mcpServers": {
"gsc-mcp-server": {
"command": "npx",
"args": [
"-y",
"mcp-remote@latest",
"http://localhost:8000/mcp"
]
}
}
} 使用MCP检查器进行调试
您可以使用 MCP检查员 测试和调试服务器。
地方发展：
npx @modelcontextprotocol/inspector fastmcp dev src/mcp_gsc/server.py对于Docker/远程服务器：
npx @modelcontextprotocol/inspector http://localhost:8000/mcp示例用法
查询搜索分析
# Ask Claude:
"Show me the top 10 search queries for https://example.com/
from 2024-01-01 to 2024-01-31"
# Claude will use:
query_search_analytics(
site_url="https://example.com/",
start_date="2024-01-01",
end_date="2024-01-31",
dimensions=["query"],
row_limit=10
)获取分析摘要
# Ask Claude:
"What's the recent search performance for https://example.com/?"
# Claude will access the resource:
gsc://sites/https%3A%2F%2Fexample.com%2F/analytics/summarySEO分析
# Ask Claude:
"Analyze the search performance for https://example.com/
and give me SEO recommendations"
# Claude will use the prompt:
analyze_search_performance(
site_url="https://example.com/",
time_period="last 30 days"
)分析的可用维度
使用时 query_search_analytics，您可以按以下方式对数据进行分组：
query-搜索查询page-登录页面country-国家device-设备类型（台式机、移动设备、平板电脑）searchAppearance-搜索结果如何显示date-日期
API范围
服务器需要以下OAuth作用域：
openid-用户标识https://www.googleapis.com/auth/userinfo.email-用户电子邮件https://www.googleapis.com/auth/webmasters-完全搜索控制台访问权限
对于只读访问，请修改 src/mcp_gsc/auth.py 使用 webmasters.readonly 范围。
发展
项目结构
mcp-gsc/
├── src/mcp_gsc/
│ ├── __init__.py # Package initialization
│ ├── server.py # Main FastMCP server
│ ├── auth.py # Google OAuth authentication
│ ├── tools.py # MCP tools (13 actions)
│ ├── resources.py # MCP resources (6 data sources)
│ ├── prompts.py # MCP prompts (4 templates)
│ └── utils.py # Utility functions
├── examples/ # Usage examples
├── pyproject.toml # Project configuration
├── .env.example # Environment variables template
└── README.md # This file运行测试
# Install dev dependencies
uv sync --all-extras
# Run tests
pytest
# Run linting
ruff check src/故障排除
身份验证错误
问题：“身份验证失败”或“401未经授权”
解决方案:
- 验证您的OAuth凭据是否正确
- 检查重定向URI是否完全匹配：
http://localhost:8000/auth/callback - 确保在Google Cloud项目中启用搜索控制台API
拒绝许可（403）
问题：访问网站时“权限被拒绝”
解决方案:
- 验证您是否可以在谷歌搜索控制台中访问该网站
- 检查您是否使用了正确的网站URL格式（例如。，
https://example.com/) - 确保您的OAuth令牌具有所需的作用域
速率限制（429）
问题：“超出费率限制”
解决方案:
- 谷歌搜索控制台API的查询限制为每分钟1200次
- 减少请求的频率
- 在客户机中实现指数回退
网站URL编码
使用带有网站URL的资源时，URL必须进行URL编码：
# Correct
gsc://sites/https%3A%2F%2Fexample.com%2F/analytics/summary
# Incorrect
gsc://sites/https://example.com//analytics/summary贡献
欢迎投稿！请随时提交拉取请求。
许可证
MIT许可证-请参阅 许可证 文件以获取详细信息。
资源
支持
对于问题和疑问：
- 在GitHub上打开一个问题
- 检查 FastMCP故障
- 审查 Google搜索控制台API文档