Gcp Logs Explorer MCP

GCP日志浏览器MCP

MCP（模型上下文协议）服务器，使Claude Code能够使用服务帐户身份验证与Google Cloud Logs Explorer进行交互。

特性

• 服务帐户身份验证：使用GCP服务帐户进行安全的无头身份验证
• 自动初始化：启动时自动连接-无需手动身份验证
• 日志查询：使用Cloud Logging筛选器语法查询日志
• 基于时间的搜索：在特定时间范围内搜索日志
• 文本搜索：按文本内容搜索日志
• 严重度分析：获取日志严重性级别的分布
• 资源发现：列出资源类型和可用日志
• 错误监视：快速访问最近的错误和关键日志
• 指标：查看基于日志的指标

先决条件

• Python 3.10或更高版本
• 启用云记录API的Google云项目
• 具有适当IAM角色的服务帐户

设置

1.创建服务帐户

1. 首选 谷歌云控制台
2. 选择您的项目
3. 引导到 IAM和管理>服务帐户
4. 点击 创建服务帐户
5. 命名它（例如，“日志资源管理器mcp”）
6. 授予这些角色：

- Logs Viewer (roles/logging.viewer)-读取日志的最低要求 - 或 Logging Admin (roles/logging.admin)-完全访问

1. 点击 完成
2. 点击服务帐户，转到 钥匙 标签
3. 点击 添加密钥>创建新密钥
4. 选择 JSON 格式
5. 下载密钥文件

2.启用所需的API

启用云日志API：

gcloud services enable logging.googleapis.com

或通过启用 云控制台

3.安装依赖项

cd gcp-log-explorer-mcp
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt

4.配置环境

复制示例环境文件：

cp .env.example .env

编辑 .env 并配置：

# Required: Your GCP project ID
GCP_PROJECT_ID=your-project-id

# Method 1: Path to service account key (RECOMMENDED)
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json

替代身份验证方法：

# Method 2: JSON string (for containers/CI)
GOOGLE_SERVICE_ACCOUNT_JSON={"type":"service_account","project_id":"..."}

# Method 3: Application Default Credentials
# Run: gcloud auth application-default login
# (No env variable needed)

5.测试服务器

直接运行服务器进行测试：

python -m src.server

如果配置正确，您将看到：

INFO - Initializing GCP Log Explorer for project: your-project-id
INFO - Authenticated as service account: log-explorer@your-project.iam.gserviceaccount.com
INFO - Successfully initialized GCP Log Explorer MCP

使用Claude代码进行配置

将此MCP服务器添加到您的Claude Code配置中：

macOS/Linux： ~/.config/claude/claude_desktop_config.json 窗户： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "gcp-log-explorer": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/absolute/path/to/gcp-log-explorer-mcp",
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/service-account-key.json"
      }
    }
  }
}

注： 您可以在配置中设置环境变量，而不是使用 .env 文件。

更新配置后重新启动Claude Code。

用法

服务器在启动时自动进行身份验证，无需手动登录！

检查状态

Check the status of the GCP log explorer

可用工具

管理

• 获取状态：检查身份验证和连接状态

测井勘探

• list_logs：列出项目中所有可用的日志
• query_logs：使用Cloud Logging筛选器语法查询日志
• query_logs_by_time_range：使用筛选器查询时间范围内的日志
• search_logs_by_text：按文本内容搜索日志
• get_resource_types：列出正在记录的资源类型
• get_log_severity_distribution：获取严重性随时间的分布
• get_log_metrics：列出基于日志的指标
• get_recent_errors：获取最近的错误和关键日志

查询示例

获取最近的错误

Show me errors from the last hour

搜索特定文本

Search logs for "database connection failed" in the last 24 hours

按严重性和时间查询

Get all ERROR logs from the last 6 hours from k8s_container resources

自定义筛选器查询

Query logs with filter: severity="WARNING" AND resource.type="gce_instance"

云日志筛选器语法

这 query_logs 该工具支持完整的云日志过滤语法：

基本过滤器

severity="ERROR"
resource.type="k8s_container"
logName="projects/my-project/logs/my-log"

基于时间的过滤器

timestamp>"2024-01-01T00:00:00Z"
timestamp"2024-01-01T00:00:00Z"

文本搜索

textPayload=~"error.*database"
jsonPayload.message=~"failed"

有关更多详细信息，请参阅 谷歌云日志查询语言.

安全说明

• 服务帐户密钥很敏感，请将其视为密码
• 安全地存储密钥文件，永远不要将其提交给版本控制
• 这 .gitignore 排除 .json 默认情况下的文件
• 使用最小权限：仅授予 roles/logging.viewer 除非需要写访问权限
• 考虑在GKE部署中使用Workload Identity，而不是密钥文件
• 定期轮换服务帐户密钥

故障排除

“无法加载凭据”

1. 验证 GOOGLE_APPLICATION_CREDENTIALS 指向正确的文件
2. 检查JSON密钥文件是否有效
3. 确保文件路径是绝对的，而不是相对的
4. 尝试跑步： gcloud auth application-default login 作为后备

“权限被拒绝”

1. 验证服务帐户是否具有所需的IAM角色：

   gcloud projects get-iam-policy YOUR_PROJECT_ID \
     --flatten="bindings[].members" \
     --filter="bindings.members:serviceAccount:YOUR_SA_EMAIL"

1. 如果缺少，则授予所需角色：

   gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
     --member="serviceAccount:YOUR_SA_EMAIL" \
     --role="roles/logging.viewer"

“未设置GCP_PROJECT_ID”

1. 创建 .env 来自文件 .env.example
2. 集 GCP_PROJECT_ID=your-project-id
3. 或者在Claude Code配置中设置它 env 章节

未找到日志

1. 验证您的项目是否有日志：访问 云日志控制台
2. 尝试调整时间范围-日志可能在搜索窗口之外
3. 检查云日志API是否已启用： gcloud services list --enabled | grep logging

发展

项目结构

gcp-log-explorer-mcp/
├── src/
│   ├── auth/
│   │   └── service_account_manager.py  # Service account authentication
│   ├── logging_client/
│   │   └── client.py                    # GCP Logging API wrapper
│   ├── tools/
│   │   └── log_tools.py                 # MCP tool definitions
│   └── server.py                        # Main MCP server
├── .env                                 # Configuration (gitignored)
├── .env.example                         # Example configuration
├── requirements.txt                     # Python dependencies
├── pyproject.toml                       # Project metadata
└── README.md

运行测试

pytest tests/

添加新工具

1. 将工具方法添加到 src/logging_client/client.py
2. 将工具定义和处理程序添加到 src/tools/log_tools.py
3. 该工具将自动在Claude Code中可用

最佳实践

用于生产

1. 使用工作负载标识 （GKE）或 IAM角色 （GCE）而不是关键文件
2. 限制权限：使用 roles/logging.viewer 用于只读访问
3. 旋转按键：如果使用密钥文件，请每90天轮换一次
4. 监控使用情况：跟踪正在访问哪些日志

为了发展

1. 使用单独的服务帐户 用于开发/测试/生产
2. 测试用 gcloud auth application-default login 创建服务帐户之前
3. 永不承诺 .env 文件或密钥文件

许可证

MIT许可证

支持

对于问题和疑问：

• 在存储库中创建问题
• 检查 MCP文件
• 审查 谷歌云日志文档