Cloud Logs MCP

IBM云记录MCP服务器

 ](https://go.dev/)    

IBM云日志的模型上下文协议（MCP）服务器，使AI助手能够与IBM云日志实例交互。包括8个可移植的代理技能，可用于Claude Code、Cursor、Gemini CLI、GitHub Copilot和30多个其他代理。

______________________________________________________________________

概述

该项目提供了两种通过AI代理使用IBM Cloud Logs的互补方法：

主要特点：

• 完整的IBM云日志API覆盖范围（88个工具）
• 8个嵌入式代理技能 agentskills.io 网站 开放标准
• 带有自动令牌刷新的IBM Cloud IAM身份验证
• 使用指数回退重试逻辑
• 可配置的速率限制
• 健康检查和指标跟踪
• 结构化日志记录

______________________________________________________________________

快速开始

安装

选项1：自制（推荐）

brew tap tareqmamari/tap
brew install logs-mcp-server
logs-mcp-server --version

Agent技能会自动安装到 ~/.agents/skills/ 安装Homebrew后。

选项2：从源代码构建

git clone https://github.com/tareqmamari/cloud-logs-mcp.git
cd cloud-logs-mcp
make deps && make build

配置

先决条件

1. 获取IBM Cloud凭据:

- API密钥：https://cloud.ibm.com/iam/apikeys - 服务URL: https://[instance-id].api.[region].logs.cloud.ibm.com - 地区： us-south, eu-de, au-syd等等。

适用于克劳德桌面

配置文件: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ibm-cloud-logs": {
      "command": "logs-mcp-server",
      "env": {
        "LOGS_SERVICE_URL": "https://[your-instance-id].api.[region].logs.cloud.ibm.com",
        "LOGS_API_KEY": "your-ibm-cloud-api-key"
      }
    }
  }
}

设置后：重新启动Claude Desktop并询问“列出我的IBM云日志警报”

适用于Microsoft 365复制副本

先决条件:

• Microsoft 365复制副本订阅（企业或企业）
• 带有Microsoft 365应用程序的Windows 11或Windows 10
• 管理员权限配置组织设置（用于企业部署）

配置选项：

选项1：个人设置（环境变量）

# PowerShell (Windows)
$env:LOGS_SERVICE_URL = "https://[your-instance-id].api.[region].logs.cloud.ibm.com"
$env:LOGS_API_KEY = "your-ibm-cloud-api-key"

# Run the server
logs-mcp-server

选项2：企业部署（Microsoft 365管理中心）

对于组织范围内的部署，请通过Microsoft 365管理中心进行配置：

1. 引导到 设置 > 集成应用程序 > 副驾驶扩展
2. 使用以下配置添加自定义MCP服务器：

- 名字：IBM云日志 - 命令: logs-mcp-server - 环境变量: - LOGS_SERVICE_URL：您的IBM Cloud Logs端点 - LOGS_API_KEY：服务ID API密钥（推荐用于企业）

设置后:

• 在Microsoft 365 Copilot中，询问“查询我的IBM云日志以查找错误”
• 在Microsoft Teams中，使用“@Copilot在IBM Cloud日志中列出我的仪表板”
• 在Outlook中，询问“显示来自IBM Cloud日志的警报”

备注：Microsoft 365 Copilot MCP支持目前处于预览阶段。配置步骤可能因租户设置而异。看 贡献.md 用于替代设置方法。

对于其他MCP客户端

看 贡献.md 有关Cline、程序使用和其他MCP兼容客户端的设置说明。

______________________________________________________________________

API 参考

工具

88种工具按功能分类：

查询操作（5个工具）

• query_logs, submit_background_query, get_background_query_status, get_background_query_data, cancel_background_query

日志摄入（1个工具）

• ingest_logs

警报管理（11个工具）

• list_alerts, get_alert, create_alert, update_alert, delete_alert
• list_alert_definitions, get_alert_definition, create_alert_definition, update_alert_definition, delete_alert_definition
• suggest_alert - SRE级警报建议 （参见 警报情报 在......下面

仪表板管理（14个工具）

• list_dashboards, get_dashboard, create_dashboard, update_dashboard, delete_dashboard
• list_dashboard_folders, get_dashboard_folder, create_dashboard_folder, update_dashboard_folder, delete_dashboard_folder
• move_dashboard_to_folder, pin_dashboard, unpin_dashboard, set_default_dashboard

政策（5个工具）

• list_policies, get_policy, create_policy, update_policy, delete_policy

Webhooks（5个工具）

• list_outgoing_webhooks, get_outgoing_webhook, create_outgoing_webhook, update_outgoing_webhook, delete_outgoing_webhook

事件到指标-E2M（5个工具）

• list_e2m, get_e2m, create_e2m, replace_e2m, delete_e2m

规则组（5个工具）

• list_rule_groups, get_rule_group, create_rule_group, update_rule_group, delete_rule_group

数据访问规则（5个工具）

• list_data_access_rules, get_data_access_rule, create_data_access_rule, update_data_access_rule, delete_data_access_rule

丰富（5个工具）

• list_enrichments, get_enrichment, create_enrichment, update_enrichment, delete_enrichment

流（5个工具）

• list_streams, get_stream, create_stream, update_stream, delete_stream

视图（5工具）

• list_views, get_view, create_view, replace_view, delete_view

资源

提示

______________________________________________________________________

警报情报

这 suggest_alert 工具提供 SRE级警报建议 基于谷歌SRE的行业最佳实践、RED/USE方法和关于警报的学术研究。

为什么使用 suggest_alert?

快速开始

"Suggest an alert for high error rate on my API service with 99.9% SLO"
"What alerts should I create for my Kafka cluster?"
"Help me set up monitoring for my PostgreSQL database"

关键参数

支持的服务类型

红色方法 服务（费率、错误、持续时间）：

• web_service, api_gateway, worker, microservice, serverless

使用方法 资源的利用率、饱和度、误差：

• database, cache, message_queue, kubernetes, storage

输出示例

{
  "suggestions": [{
    "name": "API Error Rate - Fast Burn (Page)",
    "severity": "P1",
    "methodology": "RED",
    "burn_rate_condition": {
      "slo_target": 0.999,
      "burn_rate": 14.4,
      "window_duration": "1h",
      "consumption_percent": 2.0
    },
    "suggested_actions": [
      "1. Check error logs for patterns",
      "2. Review recent deployments",
      "3. Verify dependent service health"
    ],
    "runbook_url": "/runbooks/web_service/error-rate"
  }]
}

参考文献

警报引擎执行以下建议：

• 谷歌SRE手册-警报
• “我的警报哲学” 作者：Rob Ewaschuk
• SRE工作簿-在SLO上发出警报

______________________________________________________________________

代理技能

该二进制文件在以下内容后嵌入了8个代理技能 agentskills.io 网站 开放标准。技能是可移植的指令包，可在30多个AI代理上工作，不需要运行时、身份验证或网络。

可用技能

安装技能

技能嵌入二进制文件中。使用 skills 子命令来管理它们。

# Install to ~/.agents/skills/ (user-level, available to all projects)
logs-mcp-server skills install

# Install to ./.agents/skills/ (project-level, current project only)
logs-mcp-server skills install --project

# List all available skills
logs-mcp-server skills list

# Remove installed skills
logs-mcp-server skills remove

如果您是通过Homebrew安装的，技能会自动安装到 ~/.agents/skills/ 首次安装时。

技能如何发挥作用

技能使用a 渐进式披露 最小化上下文窗口使用的模型：

1. 目录 （约200个令牌）-您的代理会看到技能名称和描述
2. 技能.md （约300行）——技能激活时按需加载
3. 参考文献 --仅在需要更深入的信息时加载详细文档

这意味着技能消耗 约2K代币按需 与MCP服务器相比 ~25K固定开销 每次谈话。看 BENCHMARK.md 以进行详细比较。

兼容代理

技能适用于任何可以从中读取markdown文件的代理 ~/.agents/skills/ 或 ./.agents/skills/:

• 克劳德代码 --自动从中发现技能 ~/.agents/skills/
• 光标 --读取项目级别 .agents/skills/
• 双子星命令行工具 --阅读 ~/.agents/skills/
• GitHub Copilot --阅读项目级技能
• Bob、Windsurf、Cline、Aider --以及通过agentskills.io标准获得的20多个

何时使用技能vs MCP

为了达到最佳效果，两者结合使用——技能提供领域知识，MCP执行操作。

______________________________________________________________________

用法示例

"Search logs for errors in the last hour"
"Create an alert when error rate exceeds 100 per minute"
"Suggest alerts for my web service with 99.9% SLO"
"What monitoring should I set up for my Redis cache?"
"List all my dashboards"
"Ingest a test log message for my-app"
"Show me all retention policies"

______________________________________________________________________

配置

环境变量

必需

加上以下其中一项：

• LOGS_SERVICE_URL -完整服务端点URL（自动提取区域和实例ID），或
• LOGS_REGION + LOGS_INSTANCE_ID -区域和实例ID（构造服务URL）

可选的

多个实例

配置多个IBM Cloud Logs实例：

{
  "mcpServers": {
    "logs-production": {
      "command": "logs-mcp-server",
      "env": {
        "LOGS_SERVICE_URL": "https://prod-id.api.us-south.logs.cloud.ibm.com",
        "LOGS_API_KEY": "prod-api-key",
        "LOGS_REGION": "us-south",
        "LOGS_INSTANCE_NAME": "Production US"
      }
    },
    "logs-staging": {
      "command": "logs-mcp-server",
      "env": {
        "LOGS_SERVICE_URL": "https://stage-id.api.us-south.logs.cloud.ibm.com",
        "LOGS_API_KEY": "staging-api-key",
        "LOGS_REGION": "us-south",
        "LOGS_INSTANCE_NAME": "Staging US"
      }
    }
  }
}

______________________________________________________________________

安全

MCP服务器最佳实践：

• 为API键使用环境变量（从不硬编码）
• 使用服务ID而不是个人API密钥进行生产
• 启用TLS验证(LOGS_TLS_VERIFY=true)
• 定期轮换API密钥（建议：90天）
• 应用最小权限原则（查看者/操作员角色）
• 使用数据访问规则按团队或角色限制日志可见性
• 启用审核日志记录(LOG_LEVEL=debug)用于合规性跟踪

代理技能安全：

• 技能不包含凭据、令牌或连接字符串
• 通过嵌入二进制文件 go:embed --构建后不可变
• 零网络攻击表面-无API调用，无数据访问
• 这 ibm-cloud-logs-access-control 技能包括安全查询模板（身份验证失败、权限升级、敏感数据访问）和合规模式（GDPR、SOC 2、多租户隔离）

看 BENCHMARK.md 详细比较MCP与技能安全。

看 安全.md 以获得全面的安全指导。

______________________________________________________________________

发展

先决条件

• 转到1.23.2+
• 制造

建筑

make deps      # Download dependencies
make build     # Build binary
make test      # Run tests
make lint      # Run linters

项目结构

├── main.go                    # Entry point with skills subcommand
├── embed_skills.go            # Embeds .agents/skills/ into binary
├── .agents/skills/            # 8 Agent Skills (agentskills.io format)
│   ├── ibm-cloud-logs-query/         # DataPrime query writing & validation
│   ├── ibm-cloud-logs-alerting/      # SRE-grade alerting with burn rate math
│   ├── ibm-cloud-logs-incident-investigation/
│   ├── ibm-cloud-logs-dashboards/
│   ├── ibm-cloud-logs-cost-optimization/
│   ├── ibm-cloud-logs-ingestion/
│   ├── ibm-cloud-logs-access-control/
│   └── ibm-cloud-logs-api-reference/
├── internal/
│   ├── auth/                  # IBM Cloud IAM authentication
│   ├── client/                # HTTP client with retry/rate limiting
│   ├── config/                # Configuration management
│   ├── tools/                 # MCP tool implementations (88 tools)
│   ├── skills/                # Skill installer
│   ├── server/                # MCP server
│   ├── health/                # Health checks
│   └── metrics/               # Metrics tracking
├── Makefile                   # Build automation
└── .goreleaser.yaml           # Release configuration

看 贡献.md 详细的开发指南包括：

• 设置其他MCP客户端（GitHub Copilot、Cline等）
• 更新API定义
• 添加新工具
• 测试策略
• 发布流程

______________________________________________________________________

故障排除

调试模式:

{
  "env": {
    "LOG_LEVEL": "debug",
    "LOG_FORMAT": "console"
  }
}

______________________________________________________________________

支持

• 问题:
• IBM云日志文档: https://cloud.ibm.com/docs/cloud-logs
• IBM云日志API: https://cloud.ibm.com/apidocs/logs-service-api

______________________________________________________________________

许可证

版权所有（c）2025。保留所有权利。