Google Cloud MCP 服务器

谷歌云MCP服务器

一个模型上下文协议服务器，连接到谷歌云服务，为与谷歌云资源交互提供上下文和工具。

这个代码库被积极维护为 krzko/谷歌云mcp，我们感谢Kris Kozak和贡献者为这个项目奠定了基础。

需求

• Node.js 24.11.0或更新版本（请参阅 .nvmrc)
• pnpm 10.21.0+通过Corepack(corepack enable && corepack use pnpm@10.21.0)

服务

支持的Google Cloud服务：

• [x] 错误报告
• [x] 日志记录
• [x] 监控
• [x] 分析器
• [x] BigQuery
• [x] 扳手
• [x] 云存储
• [x] 追踪
• [x] 支持
• [x] 文档搜索
• [x] gcloud CLI（只读包装器）

选择活动服务

设置可选 MCP_ENABLED_SERVICES 环境变量以逗号分隔 列表（例如。 spanner,trace)只加载您需要的服务。未设置或 着手 all/*，服务器会注册每个Google Cloud集成。未知 条目将被忽略，并显示启动警告和常见别名，如 metrics→监控或 errors→为了方便起见，支持错误报告。

"env": {
  "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/key.json",
  "MCP_ENABLED_SERVICES": "spanner,trace"
}

错误报告

通过自动调查和补救建议监控和分析应用程序错误：

工具： gcp-error-reporting-list-groups, gcp-error-reporting-get-group-details, gcp-error-reporting-analyse-trends

所有错误报告工具现在都会生成一个简洁的摘要，然后是JSON数据，预览组/事件和趋势桶；使用控制预览窗口 ERROR_REPORTING_* 下面列出的环境变量。

示例提示：

• “显示项目my-webapp-prod-789最后一小时的错误组”
• “获取错误组项目/my-app-123/groups/xyz789的详细信息”
• “在项目分析-prod-456中分析服务我的api的错误趋势”

日志记录

从Google Cloud日志中查询和过滤日志条目：

工具： gcp-logging-query-logs, gcp-logging-query-time-range, gcp-logging-search-comprehensive, gcp-logging-log-analytics-query

示例提示：

• “显示最近一小时my-app-prod-123项目的日志，严重性为ERROR”
• “在项目后端456中从service my api搜索包含'timeout'的日志”
• “项目compute-prod-789中资源类型gce_instance的查询日志”

要转向SQL驱动的聚合，请使用 gcp-logging-log-analytics-query。它调用Cloud Logging的日志分析SQL端点(entries:queryData / entries:readQueryResults)并自动替换 {{log_view}} 带有配置视图的占位符（默认为 projects/<project>/locations/global/buckets/_Default/views/_AllLogs).不需要显式的BigQuery数据集——该工具直接针对日志分析桶运行。

日志编辑策略

全部 gcp-logging-* 在结果离开服务器之前，工具会清除IP地址、用户标识符和请求正文。要允许受信任的操作员查看完整的有效载荷，请设置逗号分隔 LOG_PAYLOAD_FULL_ACCESS_ROLES 环境变量（默认为 security_admin,compliance_admin,site_reliability_admin)并通过以下方式提供匹配的角色 MCP_USER_ROLES/MCP_ACTIVE_ROLES。在解除有效载荷编校之前，需要进行角色匹配。

响应大小和预览控件

为了使MCP响应LLM友好，每个工具现在都会发出一个简短的元数据行，后面是JSON数据，并且可以预览大型结果集，而不是完整地流式传输。使用以下环境变量调整预览窗口：

每个响应都清楚地报告了省略了多少行/系列，以便自动化可以决定是缩小过滤器还是请求更小的时间窗口。

BigQuery

使用严格的只读强制运行联合分析：

工具： gcp-bigquery-execute-query

服务器在SQL到达BigQuery之前对其进行验证（阻止INSERT/UPDATE/CREATE/EXPORT等），支持绑定参数、可选的模拟运行，并允许您定义 defaultDataset 或 BIGQUERY_LOCATION 以避免重复限定符。输出包括查询元数据（作业ID、处理的字节数、缓存命中率）以及一个行预览 BIGQUERY_ROW_PREVIEW_LIMIT.

示例提示：

• “干跑 SELECT COUNT(*) FROM \billing.daily_costs在finops-prod-123项目中使用BIGJURY_LOCATION=US来估计扫描的字节数。"
• “执行 WITH recent AS (...) SELECT * FROM recent WHERE date >= DATE_SUB(CURRENT_DATE(), INTERVAL 7 DAY) 反对数据集营销报告。"
• “从以下网站获取消费排名前20的客户 analytics.orders 位于欧盟的项目data-warehouse-999。"

扳手

与Google Cloud Spanner数据库交互：

工具： gcp-spanner-execute-query, gcp-spanner-list-tables, gcp-spanner-list-instances, gcp-spanner-list-databases, gcp-spanner-query-count

gcp-spanner-execute-query 强制执行只读SQL；只允许使用SELECT/WITH/EXPLAIN/SHOW/DESCRIBE语句，在到达Spanner之前，所有DML/DDL都被阻止。

资源亮点： gcp-spanner-query-stats 将查询洞察（SPANNER_SYS.Query_STATS_TOP_MINUTE/10MINUTE/HOUR）作为AI就绪的JSON进行表面处理，列出1m/10m/1h的延迟和下游自动化的CPU领先者。 资源： gcp-spanner://{projectId}/{instanceId}/{databaseId}/query-plan?sql=SELECT+... （添加 &mode=analyze 用于解释分析）来审查计划、分布式连接和缺失的索引。

示例提示：

• “列出Spanner实例中的所有数据库，我在项目ecommerce-prod-123中的实例”
• “执行SQL:从项目my-app-456中的数据库用户数据库中的用户处选择COUNT（*）”
• “显示retail-789项目中数据库库存数据库中订单的表结构”

云存储

直接通过JSON API探索云存储桶和对象——不需要gcloud CLI，每个工具都是只读的，用于安全调查。

工具： gcp-storage-list-buckets, gcp-storage-get-bucket, gcp-storage-view-bucket-iam, gcp-storage-test-bucket-permissions, gcp-storage-list-objects, gcp-storage-read-object-metadata, gcp-storage-read-object-content

• gcp-storage-list-buckets 预览项目的bucket元数据（位置、存储类、标签）。提供 projectId 在查询多个租户时显式地执行。
• gcp-storage-get-bucket 曲面保留策略、生命周期规则、加密默认值和特定存储桶的标签预览。
• gcp-storage-view-bucket-iam + gcp-storage-test-bucket-permissions 允许您审核IAM绑定并验证角色是否授予特定权限。
• gcp-storage-list-objects 使用可选的前缀/分隔符过滤器和分页标记预览对象。
• gcp-storage-read-object-metadata + gcp-storage-read-object-content 获取对象元数据和截断的内容预览（文本或base64，取决于有效载荷）。这些助手从不写入或删除数据。

示例提示：

• “列表请求者在项目分析-prod-123中支付桶”
• “显示bucket gs://合规性日志的IAM绑定”
• “检查bucket gs://prod工件是否允许我使用storage.objects.delete”
• “预览前8KB的对象日志/2025-11-01.json.gz”
• “列出gs://prod-videos/2025/11/下的对象及其存储类”

监控

从谷歌云监控中检索和分析指标：

工具： gcp-monitoring-query-metrics, gcp-monitoring-list-metric-types

示例提示：

• “显示过去6小时内项目web-app-prod-123的CPU利用率指标”
• “列出项目基础架构中计算引擎的可用度量类型-456”
• “查询项目后端服务-789中实例的内存使用情况”

分析器

使用Google Cloud Profiler分析应用程序性能：

工具： gcp-profiler-list-profiles, gcp-profiler-analyse-performance, gcp-profiler-compare-trends

探查器响应共享服务器中其他地方使用的摘要+JSON形状，包括截断的分析标记(PROFILER_ANALYSIS_PREVIEW_LIMIT)以及示例配置文件预览(PROFILER_PROFILE_PREVIEW_LIMIT).

示例提示：

• “列出过去24小时内项目my-java-app-123的CPU配置文件”
• “分析项目后端prod-456中服务我的api的性能瓶颈”
• “比较项目性能测试-789中部署v1.2和v1.3的堆配置文件”

追踪

分析来自Google Cloud Trace的分布式跟踪：

工具： gcp-trace-get-trace, gcp-trace-list-traces, gcp-trace-find-from-logs

跟踪响应现在包括元数据行（项目/时间窗口/过滤器）以及包含span/Trace预览和可选层次标记的JSON有效载荷；用 TRACE_*_PREVIEW_LIMIT 变量。

示例提示：

• “获取项目distributed-app-789中ID abc123def456的跟踪详细信息”
• “显示项目微服务prod-123在过去一小时的失败痕迹”
• “在项目web-backend-456中查找与跟踪xyz789相关的日志”
• “项目ecommerce-prod-321中服务结账api的查询跟踪”

支持

直接从MCP处理谷歌云支持案例：

工具： gcp-support-list-cases, gcp-support-search-cases, gcp-support-get-case, gcp-support-create-case, gcp-support-update-case, gcp-support-close-case, gcp-support-list-comments, gcp-support-create-comment, gcp-support-list-attachments, gcp-support-search-classifications

支持响应现在会发出经过净化的案例/评论/附件JSON以及简短的调查说明。使用 SUPPORT_*_PREVIEW_LIMIT 平衡细节与有效载荷大小的变量。

示例提示：

• “列出项目/my-prod-123的未结P1案例”
• “为项目/foo/cases/1234567890123456789添加更新，总结缓解措施”
• “搜索‘服务帐户访问权限’的分类”

文档搜索

在不离开网络的情况下，查找最接近的自然语言提示官方Google Cloud文档。文档工具不是代理实时流量，而是对本地JSON目录中的条目进行评分(docs/catalog/google-cloud-docs.json 默认情况下）使用TF-IDF+余弦相似度，因此查询意图比简单的字符串重叠更重要。无论何时需要新的覆盖范围，都可以手动或通过您信任的任何内部爬虫更新该文件，MCP服务器将完全脱机应答。

工具： google-cloud-docs-search

要扩展目录，请添加形状如下的条目：

{
  "title": "Cloud Run resource limits",
  "url": "https://cloud.google.com/run/docs/configuring/memory-limits",
  "summary": "Lists CPU, memory, and request limits for Cloud Run services and jobs.",
  "tags": ["cloud run", "limits", "cpu", "memory"],
  "product": "cloud-run",
  "lastReviewed": "2025-06-30"
}

文档目录资源(docs://)

MCP资源公开相同的离线目录，因此代理可以在不离开客户端的情况下浏览和链接文档：

填充 docs/catalog/google-cloud-docs.json （或您的覆盖路径）以保持MCP工具和资源的最新状态。每当更新JSON时，重新启动服务器或清除文档缓存，以便请求获取新条目。

gcloud命令行界面（只读）

当您只需要读取操作并且必须保证零副作用时，将官方gcloud CLI包装在MCP工具后面。

工具： gcloud-run-read-command

示例提示：

• “跑 gcloud projects list 使用这些参数： ['gcloud','projects','list','--format=json']"
• “通过调用列出云日志接收器 ['gcloud','logging','sinks','list']"
• “描述监控通知通道 projects/example/channels/123 （命令： ['gcloud','monitoring','channels','describe','projects/...'])"

如果命令被阻止，该工具会返回策略代码和原因，以便您可以调整或回退到人工操作员。

只接受谷歌拥有的域名，因此拼写错误或第三方链接会自动跳过。

示例提示：

• “找到教如何从云存储触发云运行事件的最佳文档”
• “保护Redis内存存储的官方指导是什么？”
• “在日语文档中Cloud Logging 确认费用“

Deep Wiki / 详细文档

• 深潜（英语）
• 详细指南（日语）
• 离线文档搜索

快速开始

配置后，您可以通过MCP工具与Google Cloud服务进行交互：

"Show me errors from project ecommerce-api-456 in the last hour"
"Find logs containing 'database timeout' from project backend-prod-321 yesterday"
"List Spanner databases in instance prod-db for project data-store-654"
"Run a BigQuery query to list the latest 20 orders in project analytics-prod-888"
"What's the CPU usage of Compute Engine instances in project infrastructure-987?"
"Compare recent heap profiles in project performance-test-789"
"List traces for checkout-api in project ecommerce-prod-321 during the past day"

认证

此服务器支持Google Cloud的两种身份验证方法：

1. 服务帐户密钥文件 （推荐）：设置 GOOGLE_APPLICATION_CREDENTIALS 将环境变量设置为服务帐户密钥文件的路径。这是标准的Google Cloud身份验证方法。

2. 环境变量：设置 GOOGLE_CLIENT_EMAIL 和 GOOGLE_PRIVATE_KEY 环境变量直接。这对于存储密钥文件不切实际的环境非常有用。

服务器也将使用 GOOGLE_CLOUD_PROJECT 如果设置了环境变量，否则它将尝试从身份验证凭据中确定项目ID。

安装

# Clone the repository
git clone https://github.com/krzko/google-cloud-mcp.git
cd google-cloud-mcp

# Install dependencies
pnpm install

# Build
pnpm build

通过Google Cloud进行身份验证：

gcloud auth application-default login

配置 mcpServers 在您的客户中：

{
  "mcpServers": {
      "google-cloud-mcp": {
          "command": "node",
          "args": [
              "/Users/foo/code/google-cloud-mcp/dist/index.js"
          ],
          "env": {
              "GOOGLE_APPLICATION_CREDENTIALS": "/Users/foo/.config/gcloud/application_default_credentials.json"
          }
      }
  }
}

发展

启动服务器

# Build the project
pnpm build

# Start the server
pnpm start

开发模式

# Build the project
pnpm build

# Start the server and inspector
npx -y @modelcontextprotocol/inspector node dist/index.js

独立调用

集 MCP_SERVER_MODE=standalone 按需启动MCP服务器，并在客户端断开连接后立即退出。这跳过了保活心跳，非常适合Smithery或其他按请求启动的主机。

MCP_SERVER_MODE=standalone pnpm start

如果您通过Smithery部署，则捆绑 smithery.yaml 现在接受 standalone: true 在其配置块中自动导出相同的环境变量。

故障排除

服务器超时问题

如果在使用Smithery运行服务器时遇到超时问题，请尝试以下操作：

1. 通过设置启用调试日志记录 debug: true 在您的配置中
2. 确保 lazyAuth: true 设置为将身份验证推迟到实际需要时
3. 确保您的凭据文件可访问且有效
4. 检查日志中是否有任何错误消息

重要：操作仍然需要身份验证，但启用延迟加载后，服务器将立即启动并在需要时进行身份验证，而不是在初始化期间。

身份验证问题

服务器支持两种身份验证方法：

1. 服务帐户密钥文件：设置 GOOGLE_APPLICATION_CREDENTIALS 将环境变量设置为服务帐户密钥文件的路径
2. 环境变量：设置 GOOGLE_CLIENT_EMAIL 和 GOOGLE_PRIVATE_KEY 环境变量

如果您遇到身份验证问题，请确保：

• 您的服务帐户具有必要的权限
• 密钥文件格式正确且可访问
• 环境变量设置正确