IBM云记录MCP服务器
IBM云日志的模型上下文协议(MCP)服务器,使AI助手能够与IBM云日志实例交互。包括8个可移植的代理技能,可用于Claude Code、Cursor、Gemini CLI、GitHub Copilot和30多个其他代理。
概述
该项目提供了两种通过AI代理使用IBM Cloud Logs的互补方法:
| MCP服务器 | 代理技能 | |
|---|---|---|
| 什么 | 通过JSON-RPC使用88个工具运行Go服务器 | 8个可移植指令包(markdown+JSON) |
| 当 | 实时日志查询、CRUD操作、实时监控 | 查询编写、架构指导、离线参考 |
| 需要 | 二进制+API密钥+网络 | 无-由您的代理按需加载 |
| 适用于 | Claude Desktop,任何MCP客户端 | Claude Code,Cursor,Gemini CLI,GitHub Copilot,30多个代理 |
主要特点:
- 完整的IBM云日志API覆盖范围(88个工具)
- 8个嵌入式代理技能 agentskills.io 网站 开放标准
- 带有自动令牌刷新的IBM Cloud IAM身份验证
- 使用指数回退重试逻辑
- 可配置的速率限制
- 健康检查和指标跟踪
- 结构化日志记录
快速开始
安装
选项1:自制(推荐)```bash
brew tap tareqmamari/tap
brew install logs-mcp-server
logs-mcp-server --version
Agent技能会自动安装到 `~/.agents/skills/` 安装Homebrew后。
**选项2:从源代码构建**```bash
git clone https://github.com/tareqmamari/cloud-logs-mcp.git
cd cloud-logs-mcp
make deps && make build
配置
先决条件
- 获取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````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
# 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管理中心进行配置:
- 引导到 设置 > 集成应用程序 > 副驾驶扩展
- 使用以下配置添加自定义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_alertlist_alert_definitions,get_alert_definition,create_alert_definition,update_alert_definition,delete_alert_definitionsuggest_alert- SRE级警报建议 (参见 警报情报 在......下面
仪表板管理(14个工具)
list_dashboards,get_dashboard,create_dashboard,update_dashboard,delete_dashboardlist_dashboard_folders,get_dashboard_folder,create_dashboard_folder,update_dashboard_folder,delete_dashboard_foldermove_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
资源
| 资源URI | 描述 |
|---|---|
config://current |
服务器配置 |
metrics://server |
服务器指标 |
health://status |
健康检查状态 |
提示
| 提示 | 描述 |
|---|---|
investigate_errors |
错误峰值调查指南 |
setup_monitoring |
为服务设置监控 |
test_log_ingestion |
测试日志摄取工作流程 |
create_dashboard_workflow |
仪表板创建向导 |
compare_environments |
比较不同的环境 |
debugging_workflow |
系统调试方法 |
optimize_retention |
优化日志保留成本 |
警报情报
这 suggest_alert 工具提供 SRE级警报建议 基于谷歌SRE的行业最佳实践、RED/USE方法和关于警报的学术研究。
为什么使用 suggest_alert?
| 问题 | 如何 suggest_alert 帮助 |
|---|---|
| 警惕疲劳 | 使用燃烧率警报将噪音降低90%+ |
| 假阳性 | 多窗口验证可防止警报摆动 |
| 静态阈值 | 为季节性指标建议动态基线 |
| 缺少上下文 | 自动生成runbook模板和操作 |
| 错误的方法 | 自动选择红色(服务)与使用(资源) |
快速开始```
"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"
### 关键参数
|参数|说明|示例|
|-----------|-------------|---------|
| `service_type` |组件类型(如果未提供,则自动检测)| `web_service`, `database`, `message_queue` |
| `slo_target` |SLO目标(启用燃烧率警报)| `0.999` (99.9%) |
| `is_user_facing` |影响严重程度分类| `true` → P1符合条件|
| `use_case` |自然语言描述| `"high latency on checkout"` |
### 支持的服务类型
**红色方法** 服务(费率、错误、持续时间):
- `web_service`, `api_gateway`, `worker`, `microservice`, `serverless`
**使用方法** 资源的利用率、饱和度、误差:
- `database`, `cache`, `message_queue`, `kubernetes`, `storage`
### 输出示例```json
{
"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代理上工作,不需要运行时、身份验证或网络。
可用技能
| 技能 | 描述 |
|---|---|
ibm-cloud-logs-query |
DataPrime和Lucene查询编写、验证和自动更正 |
ibm-cloud-logs-alerting |
SRE级警报,采用RED/USE方法和燃烧率数学 |
ibm-cloud-logs-incident-investigation |
基于启发式模式匹配的系统性事件调查 |
ibm-cloud-logs-dashboards |
使用DataPrime驱动的小部件进行仪表板设计 |
ibm-cloud-logs-cost-optimization |
TCO策略、数据层选择和事件到指标 |
ibm-cloud-logs-ingestion |
日志摄取、解析规则和丰富 |
ibm-cloud-logs-access-control |
数据访问规则、审计日志记录和合规模式 |
ibm-cloud-logs-api-reference |
所有88个工具端点的完整API参考 |
安装技能
技能嵌入二进制文件中。使用 skills 子命令来管理它们。```bash
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个令牌)-您的代理会看到技能名称和描述
1. **技能.md** (约300行)——技能激活时按需加载
1. **参考文献** --仅在需要更深入的信息时加载详细文档
这意味着技能消耗 **约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|
|编写DataPrime查询(不执行)|技能|
|创建或管理警报|MCP|
|设计警报策略|技能|
|调试实时生产事件|MCP|
|学习调查方法|技能|
|设置仪表板|MCP|
|规划仪表板布局和查询|技能|
|离线查询/配置指导(不执行)|技能|
|IBM云日志上的任何CRUD操作|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_API_KEY |
IBM云API密钥 |
加上以下其中一项:
LOGS_SERVICE_URL-完整服务端点URL(自动提取区域和实例ID),或LOGS_REGION+LOGS_INSTANCE_ID-区域和实例ID(构造服务URL)
可选的
| 变量 | 默认值 | 描述 |
|---|---|---|
LOGS_TIMEOUT |
30s |
HTTP请求超时 |
LOGS_MAX_RETRIES |
3 |
最大重试次数 |
LOGS_RATE_LIMIT |
100 |
每秒请求数 |
LOG_LEVEL |
info |
日志级别(调试/信息/警告/错误) |
LOG_FORMAT |
json |
日志格式(json/控制台) |
多个实例
配置多个IBM Cloud Logs实例:```json
{
"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+
- 制造
### 建筑```bash
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定义
- 添加新工具
- 测试策略
- 发布流程
______________________________________________________________________
## 故障排除
|问题|解决方案|
|-------|----------|
|工具未显示|使用绝对二进制路径,完全重新启动MCP客户端|
| `401 Unauthorized` |检查API密钥有效性和IAM权限|
| `429 Too Many Requests` |减少 `LOGS_RATE_LIMIT` 或请求增加配额|
|连接超时|增加 `LOGS_TIMEOUT` 或检查网络|
**调试模式**:```json
{
"env": {
"LOG_LEVEL": "debug",
"LOG_FORMAT": "console"
}
}
支持
- 问题: GitHub问题
- IBM云日志文档: https://cloud.ibm.com/docs/cloud-logs
- IBM云日志API: https://cloud.ibm.com/apidocs/logs-service-api
许可证
版权所有(c)2025。保留所有权利。
