monitoring-mcp

# 监测MCP服务器 <p align="center"> <a href="https://github.com/casey/just"><img src="https://img.shields.io/badge/just-ready_to_go-7c5cfc?style=flat-square&logo=just&logoColor=white" alt="Just"></a> <a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff"></a> <a href="https://python.org"><img src="https://img.shields.io/badge/Python-3.13+-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python"></a> <a href="https://github.com/PrefectHQ/fastmcp"><img src="https://img.shields.io/badge/FastMCP-3.2-7c5cfc?style=flat-square" alt="FastMCP"></a> </p> > 📖 **[安装指南](INSTALL.md)** — 快速开始，手动设置和故障排除 [](https://github.com/sandraschi/monitoring-mcp/actions) [](https://codecov.io/gh/sandraschi/monitoring-mcp) [](https://pypi.org/project/monitoring-mcp/) [](https://pypi.org/project/monitoring-mcp/) [](https://www.python.org/) [](https://opensource.org/licenses/MIT) [](https://github.com/jlowin/fastmcp) [](https://grafana.com) [](https://prometheus.io) [](https://grafana.com/oss/loki/) [](https://github.com/sandraschi/monitoring-mcp) [](https://github.com/sandraschi/monitoring-mcp) [](https://github.com/sandraschi/monitoring-mcp/issues) [](https://modelcontextprotocol.io/) [](https://github.com/sandraschi/monitoring-mcp/pulse) [](http://makeapullrequest.com) *一个全面的FastMCP 3.1.0驱动的监测服务器，提供智能化的Grafana、Prometheus和Loki生态系统运维能力，并为DevOps工作流提供对话式AI辅助。* ## 快速开始 ```powershell git clone https://github.com/sandraschi/monitoring-mcp cd monitoring-mcp just ``` 这将打开一个交互式仪表板，显示所有可用的命令。运行`just bootstrap`安装依赖项，然后运行`just serve`或`just dev`启动服务。 ### 手动设置 如果您没有安装`just`： ## 功能 ### **FastMCP 3.1.0集成** - **对话式工具返回** - 适合AI的响应，提供可行的洞察力 - **采样能力** - 大型结果集的智能数据采样 - **持久存储** - 配置和状态的磁盘存储后端 - **生产就绪** - 面向高性能监控操作的构建 ### **全面的监控工具** #### **Grafana管理** (`grafana_management`) - **仪表板操作**：列出、创建、更新、删除和分析仪表板 - **数据源查询**：对配置的数据源执行查询 - **面板管理**：添加和修改仪表板面板 - **警报配置**：设置仪表板指标的警报规则 - **AI驱动的分析**：智能仪表板优化建议 #### **Prometheus监控** (`prometheus_monitoring`) - **指标查询**：执行PromQL查询，并进行智能采样 - **范围查询**：时间序列分析，自动优化 - **目标健康**：监控抓取目标状态和连接性 - **警报管理**：列出活动警报和管理警报规则 - **性能分析**：查询优化和瓶颈检测 #### **Loki日志记录** (`loki_logging`) - **日志查询**：执行LogQL查询，并进行模式识别 - **实时跟踪**：流式传输实时日志，并配置限制 - **异常检测**：AI驱动的日志模式分析 - **错误关联**：链接错误日志和系统事件 - **请求跟踪**：在日志流中跟踪请求流程 #### **跨系统关联** (`cross_system_correlation`) - **事件分析**：关联指标、日志和跟踪以进行根本原因分析 - **性能关联**：链接性能指标和系统事件 - **错误关联**：在系统之间连接错误模式 - **健康评估**：综合系统健康评分 - **预测洞察**：AI驱动的趋势分析和建议 #### **状态和健康监控** (`monitoring_status`) - **系统健康检查**：跨所有系统的综合健康评估 - **连接测试**：验证与所有监控组件的连接 - **配置验证**：验证系统配置和设置 - **数据流监控**：检查监控系统之间的数据流 - **警报状态**：监控警报系统健康和活动警报 ### **AI驱动的智能** - **对话式响应**：自然语言摘要和可行的洞察力 - **智能采样**：大型数据集的自动数据缩减 - **根本原因分析**：AI辅助事件调查 - **优化建议**：性能和配置建议 - **模式识别**：自动异常检测和趋势分析 ### **企业功能** - **持久配置**：加密存储，平台感知路径 - **速率限制**：智能请求限制和错误处理 - **结构化日志记录**：JSON格式日志，丰富上下文 - **错误恢复**：优雅的降级和自动重试逻辑 - **安全**：API密钥管理支持身份验证 ## 会话用法示例 这些示例展示了用户如何通过自然语言会话与MCP服务器交互，就像在Claude Desktop或其他支持MCP的应用程序中一样。 ### **系统健康检查会话** **用户：** “检查我的监控系统的整体健康状况” **MCP服务器响应：** > “我发现您的监控系统大部分是健康的！ > > **系统状态：已降级** （4个组件中有3个健康） > > **Grafana**：健康（12个仪表板，3个数据源配置） > **Prometheus**：健康（247个目标，98%正常） > **Loki**：不健康（连接超时 - 检查Loki服务是否正在运行） > **整体**：1个问题需要注意 > > **建议：** 启动Loki服务并运行连接测试以验证修复。” --- ### **事件调查会话** **用户：** “今天下午3点15分，我们的API响应时间突然增加。您能帮助我调查发生了什么吗？” **MCP服务器响应：** > “我将调查下午3点15分API响应时间激增的原因。让我关联指标、日志和系统事件。 > > **时间线分析：** > - **下午3点15分**：API延迟从45毫秒跳跃到890毫秒 > - **指标**：内存使用率激增至web-01服务器的92% > - **日志**：web-api服务中有多个“GC overhead limit exceeded”错误 > > **已识别根本原因：** > 内存压力触发了垃圾回收风暴，导致响应延迟。 > > **证据：** > - 内存使用率：92%（阈值：80%） > - GC暂停时间：450毫秒（正常：<50毫秒） > - 错误日志：5分钟窗口内有47个“GC overhead”异常 > > **建议：** > 1. 升级web-01实例（当前t3.medium） > 2. 调整JVM GC设置（-XX:+UseG1GC -XX:MaxGCPauseMillis=100） > 3. 在75%阈值下添加内存监控警报” --- ### **性能分析会话** **用户：** “为什么这个星期我们的数据库查询性能下降了？” **MCP服务器响应：** > “我已经分析了您过去一周的数据库性能。以下是我的发现： > > **性能趋势：** 查询响应时间下降23% > > **关键指标：** > - 平均查询时间：450毫秒（高于320毫秒） > - 慢查询（> 1秒）：15%（高于8%） > - 连接池利用率：89%（高于72%） > > **关联事件：** > - **星期二 14:30**：数据库重启（维护窗口） > - **星期三**：索引重建完成（预期的性能下降） > - **星期五**：连接池多次耗尽 > > **性能洞察：** > 1. **连接池争用**：89%的利用率表明需要增加池大小 > 2. **索引碎片**：最近的重建显示出40%的改进潜力 > 3. **内存压力**：缓冲区缓存命中率下降至87% > > **行动项目：** > - 增加连接池大小25% > - 调度定期索引维护 > - 添加连接池利用率> 80%的监控” --- ### **日志分析会话** **用户：** “我在日志中看到身份验证失败。可以分析模式吗？” **MCP服务器响应：** > “我已经分析了过去24小时内您的身份验证失败模式： > > **摘要：** 检测到1,247次登录失败尝试 > > **主要失败原因：** > - **无效凭证**：68%（851次尝试）- 正常用户错误 > - **账户锁定**：22%（275次尝试）- 暴力保护 > - **令牌过期**：8%（100次尝试）- 会话超时 > - **IP阻止**：2%（21次尝试）- 安全措施 > > **检测到的可疑模式：** > - **IP 192.168.1.100**：10分钟内连续45次失败 > - **用户'admin'**：被89个不同IP针对 > - **时间模式**：UTC时间2-4点峰值 > > **安全建议：** > 1. 暂时阻止IP 192.168.1.100（暴力尝试） > 2. 对失败登录实施渐进延迟 > 3. 为可疑区域添加地理封锁 > 4. 为管理员账户启用MFA” --- ### **仪表板创建会话** **用户：** “创建一个显示我们服务健康状况的仪表板” **MCP服务器响应：** > “我将为您创建一个全面的服务健康仪表板！ > > **已创建仪表板：** ‘服务健康概览’ > **UID：** svc-health-2024 > > **包含的面板：** > > 1. **服务状态网格** - 服务的实时健康状态 > 2. **错误率趋势** - 1小时、24小时、7天错误率图表 > 3. **响应时间分布** - P50、P95、P99延迟指标 > 4. **资源利用率** - CPU、内存、磁盘、网络利用率 > 5. **警报摘要** - 按严重性分类的活动警报 > 6. **主要错误源** - 产生最多错误的服务 > > **连接的数据源：** > - Prometheus（指标） > - Loki（日志） > - Grafana（可视化） > > **自动刷新：** 30秒 > **时间范围：** 最近1小时 > > **访问：** 可在 `/d/svc-health-2024/service-health-overview` 访问 > > 仪表板现已上线，将帮助您一目了然地监控服务健康状况！” --- ### **配置验证会话** **用户：** “验证我的监控配置是否正确” **MCP服务器响应：** > “让我检查您的监控系统在所有组件的配置： > > **配置验证结果：** **全部有效** > > **Grafana（http://grafana:3000）：** > - API连接确认 > - 配置了3个数据源（Prometheus、Loki、TestData） > - 可用12个仪表板 > - 已验证管理员权限 > > **Prometheus（http://prometheus:9090）：** > - 查询API响应 > - 配置了247个抓取目标 > - 目标健康（243/247上线） > - 活动警报规则：45条 > > **Loki（http://loki:3100）：** > - LogQL API功能正常 > - 8个不同的日志流 > - 已摄入2.3GB日志（过去24小时） > - 保留策略：30天 > > **系统间集成：** > - Grafana可以查询Prometheus数据 > - Grafana可以查询Loki日志 > - 警报路由配置 > - 仪表板链接功能正常 > > **建议：** > 1. **4个不健康的抓取目标** 需要调查 > 2. **考虑增加保留期** 如果您需要更长的日志历史 > 3. **添加更多警报规则** 适用于关键服务 > > 您的监控堆栈配置正确且运行正常！ " --- ## API用法示例 适用于直接与MCP工具集成的开发人员： ### Grafana仪表板管理 ```python # 列出所有仪表板 await grafana_management(operation="list_dashboards") # 创建新仪表板 await grafana_management( operation="create_dashboard", dashboard_data={ "title": "系统概述", "tags": ["系统", "概述"], "panels": [...] } ) ``` ### Prometheus指标分析 ```python # 查询系统CPU使用率 await prometheus_monitoring( operation="query_metrics", query="100 - (avg by(instance) (irate(node_cpu_seconds_total{mode='idle'}[5m])) * 100)" ) ``` ### Loki日志分析 ```python # 搜索错误模式 await loki_logging( operation="search_errors", query='{job="web-api"} |= "ERROR" or "Exception"' ) ``` ### 跨系统事件分析 ```python # 关联事件数据 await cross_system_correlation( operation="correlate_incident", incident_description="API响应时间激增" ) ``` ### 健康监控 ```python # 检查整体系统健康状况 await monitoring_status(operation="system_health") ``` ## 安装 ### 依赖项 - 已安装 [uv](https://docs.astral.sh/uv/) （推荐） - Python 3.12+ ### 快速开始 使用`uvx`立即运行： ```bash uvx monitoring-mcp ``` ### Claude Desktop集成 添加到您的`claude_desktop_config.json`： ```json "mcpServers": { "monitoring-mcp": { "command": "uv", "args": ["--directory", "D:/Dev/repos/monitoring-mcp", "run", "monitoring-mcp"] } } ``` ### 依赖项 - Python 3.10+ - 访问Grafana、Prometheus和Loki实例 - FastMCP 3.1.0+（自动安装） ### 从PyPI（推荐） ```bash pip install monitoring-mcp ``` ### 从源码 ```bash git clone https://github.com/sandraschi/monitoring-mcp.git cd monitoring-mcp uv pip install -e .[dev] ``` ### 配置 创建`.env`文件或设置环境变量： ```bash # 监控端点 MONITORING_MCP_GRAFANA_URL=http://localhost:3000 MONITORING_MCP_PROMETHEUS_URL=http://localhost:9090 MONITORING_MCP_LOKI_URL=http://localhost:3100 # 认证（可选） MONITORING_MCP_GRAFANA_API_KEY=your_grafana_api_key MONITORING_MCP_GRAFANA_USERNAME=your_username MONITORING_MCP_GRAFANA_PASSWORD=your_password # 性能设置 MONITORING_MCP_REQUEST_TIMEOUT=30 MONITORING_MCP_MAX_CONCURRENT_REQUESTS=10 MONITORING_MCP_MAX_RESULTS_LIMIT=1000 # 采样配置 MONITORING_MCP_ENABLE_SAMPLING=true MONITORING_MCP_SAMPLING_THRESHOLD=10000 MONITORING_MCP_SAMPLING_RATE=0.1 ``` ## 配置 ### 环境变量 | 变量名 | 描述 | 默认值 | |----------|-------------|---------| | `MONITORING_MCP_GRAFANA_URL` | Grafana服务器URL | `http://localhost:3000` | | `MONITORING_MCP_PROMETHEUS_URL` | Prometheus服务器URL | `http://localhost:9090` | | `MONITORING_MCP_LOKI_URL` | Loki服务器URL | `http://localhost:3100` | | `MONITORING_MCP_REQUEST_TIMEOUT` | 请求超时（秒） | `30` | | `MONITORING_MCP_MAX_RESULTS_LIMIT` | 每查询最大结果数 | `1000` | | `MONITORING_MCP_ENABLE_SAMPLING` | 启用智能采样 | `true` | ### 认证 #### Grafana认证 - **API密钥**（推荐）：设置`MONITORING_MCP_GRAFANA_API_KEY` - **用户名/密码**：同时设置`MONITORING_MCP_GRAFANA_USERNAME`和`MONITORING_MCP_GRAFANA_PASSWORD` #### Prometheus & Loki - 目前使用直接HTTP访问（本地设置不需要身份验证） - 对于生产部署，请配置带有身份验证的反向代理 ## 快速开始 ### 1. 启动服务器 ```bash # 使用已安装的软件包 monitoring-mcp # 或直接使用Python python -m monitoring_mcp ``` ### 2. 配置Claude Desktop 添加到您的`claude_desktop_config.json`： ```json { "mcpServers": { "monitoring": { "command": "python", "args": ["-m", "monitoring_mcp"], "env": { "MONITORING_MCP_GRAFANA_URL": "http://your-grafana:3000", "MONITORING_MCP_PROMETHEUS_URL": "http://your-prometheus:9090", "MONITORING_MCP_LOKI_URL": "http://your-loki:3100" } } } } ``` ### 3. 测试连接 ```python # 检查系统健康状况 result = await monitoring_status(operation="system_health") print(f"系统状态：{result['health_status']['overall_status']}") # 查询一个简单指标 result = await prometheus_monitoring( operation="query_metrics", query="up" ) print(f"找到 {result['result_count']} 个指标系列") ``` ## 监控架构 ``` 监控MCP服务器 Portmanteau 工具 Grafana Prometheus Loki 管理 监控 日志 Grafana Prometheus Loki 仪表板 使用指标 日志 & 面板 和警报 跨系统 相关性引擎 事件分析 根本原因检测 性能洞察 健康评估 ``` ## 工具参考 </div> ### Grafana 管理 (`grafana_management`) | 操作 | 描述 | |-----------|-------------| | `list_dashboards` | 列出所有仪表盘及其元数据 | | `get_dashboard` | 获取特定仪表盘 | | `create_dashboard` | 创建新仪表盘 | | `update_dashboard` | 修改现有仪表盘 | | `delete_dashboard` | 删除仪表盘 | | `search_dashboards` | 按条件搜索仪表盘 | | `list_datasources` | 列出已配置的数据源 | | `query_datasource` | 对数据源执行查询 | | `analyze_dashboard` | AI 驱动的仪表盘分析 | ### Prometheus 监控 (`prometheus_monitoring`) | 操作 | 描述 | |-----------|-------------| | `query_metrics` | 执行即时 PromQL 查询 | | `query_range` | 执行范围 PromQL 查询 | | `list_targets` | 列出抓取目标及其状态 | | `get_target_health` | 检查特定目标的健康状态 | | `list_rules` | 列出告警和记录规则 | | `list_alerts` | 列出活跃告警 | | `analyze_metrics` | AI 驱动的指标分析 | | `optimize_queries` | 查询优化建议 | ### Loki 日志 (`loki_logging`) | 操作 | 描述 | |-----------|-------------| | `query_logs` | 执行即时 LogQL 查询 | | `query_range` | 执行范围 LogQL 查询 | | `tail_logs` | 流式日志 | | `analyze_logs` | AI 驱动的日志模式分析 | | `detect_anomalies` | 识别异常日志模式 | | `search_errors` | 查找错误信息和异常 | | `trace_requests` | 跟踪请求 | | `get_labels` | 列出可用的日志标签 | ### 跨系统关联 (`cross_system_correlation`) | 操作 | 描述 | |-----------|-------------| | `correlate_incident` | 分析系统间的事件 | | `find_root_cause` | AI 驱动的根本原因分析 | | `performance_correlation` | 将性能与事件关联 | | `error_correlation` | 连接错误模式 | | `health_assessment` | 全面的系统健康评估 | | `service_dependency_map` | 映射服务关系 | ### 状态监控 (`monitoring_status`) | 操作 | 描述 | |-----------|-------------| | `system_health` | 全面的系统健康检查 | | `connectivity_test` | 测试系统连通性 | | `configuration_validation` | 验证配置 | | `performance_metrics` | 监控系统性能 | | `data_flow_status` | 检查数据流健康 | | `alert_status` | 监控告警系统 | ## 开发 [](https://github.com/astral-sh/ruff) [](https://github.com/psf/black) [](https://pycqa.github.io/isort/) [](http://mypy-lang.org/) [](https://github.com/pytest-dev/pytest) [](https://docs.python.org/3/library/asyncio.html) [](https://fastapi.tiangolo.com/) ### 设置开发环境 ```bash # 安装开发依赖 uv pip install -e .[dev] # 运行测试 pytest # 运行 linting ruff check . # 格式化代码 ruff format . # 类型检查 mypy src/ ``` ### 测试 ```bash # 运行所有测试 pytest # 运行覆盖率测试 pytest --cov=monitoring_mcp --cov-report=html # 运行特定测试类别 pytest tests/unit/ -v pytest tests/integration/ -v ``` ### Docker 开发 ```bash # 构建开发镜像 docker build -t monitoring-mcp:dev -f Dockerfile.dev . # 运行热重载 docker run -p 8000:8000 -v $(pwd):/app monitoring-mcp:dev ``` ## 文档 ### 指南和文档 - **[API 参考](docs/api/)** - 完整的 API 文档 - **[Grafana 集成](docs/grafana/)** - Grafana 特定指南 - **[Prometheus 查询](docs/prometheus/)** - PromQL 实践 - **[Loki 查询](docs/loki/)** - LogQL 模式和示例 - **[关联分析](docs/correlation/)** - 跨系统分析技术 - **[故障排除](docs/troubleshooting/)** - 常见问题和解决方案 ### 架构文档 - **[系统架构](docs/architecture/)** - 系统设计和组件 - **[性能指南](docs/performance/)** - 优化和扩展 - **[安全](docs/security/)** - 安全考虑和实践 - **[部署](docs/deployment/)** - 生产部署指南 ## 贡献 我们欢迎贡献！请参阅我们的 [贡献指南](CONTRIBUTING.md) 获取详细信息。 ### 开发工作流 1. 分叉仓库 2. 创建功能分支 (`git checkout -b feature/-feature`) 3. 进行更改并添加全面测试 4. 运行完整测试套件：`make test-all` 5. 根据需要更新文档 6. 提交拉取请求 ### 代码标准 - **FastMCP 3.1.0+**: 使用最新功能和模式 - **类型提示**: 需要完整的类型覆盖 - **异步优先**: 所有操作应异步执行 - **对话式**: 工具响应应 AI 友好 - **文档**: 需要全面的文档字符串和示例 ## 🛡️ 工业质量栈 该项目遵循 **SOTA 14.1** 工业标准，用于高保真代理编排： - **Python（核心）**: [Ruff](https://astral.sh/ruff) 用于 linting 和格式化。对核心处理程序中的 `print` 语句零容忍度 (`T201`)。 - **Webapp（UI）**: [Biome](https://biomejs.dev/) 用于毫秒级 linting。严格执行 `noConsoleLog`。 - **协议合规**: 加强 `stdout/stderr` 隔离，以确保崩溃抗性 JSON-RPC 通信。 - **自动化**: [Justfile](./justfile) 适用于所有舰队操作 (`just lint`, `just fix`, `just dev`)。 - **安全**: 通过 `bandit` 和 `safety` 进行自动审计。 ## 许可证 该项目在 MIT 许可证下许可 - 请参阅 [LICENSE](LICENSE) 文件获取详细信息。 ## 致谢 - **FastMCP 团队** - 优秀的 MCP 框架 - **Grafana Labs** - Grafana、Prometheus 和 Loki - **OpenTelemetry 社区** - 可观测性标准 - **Pydantic 团队** - 强大的数据验证 --- **使用 FastMCP 3.1.0 构建，用于智能监控操作**