允许 LLM 通过 MCP 协议与 Prometheus 交互，执行 PromQL 查询、发现指标并获取内置文档支持的 Go 语言服务器。
本项目是一个基于 Go 语言实现的 MCP（Model Context Protocol）服务器，旨在打通大语言模型与 Prometheus 可观测性平台之间的交互链路。通过封装完整的 Prometheus HTTP API，它支持 LLM 执行即时与范围 PromQL 查询、发现标签与序列、读取告警与规则状态。为提升 LLM 交互质量，项目内置了 prometheus/docs 离线文档子模块，并提供 TOON 编码与响应截断机制以大幅优化 Token 消耗。
核心能力#
- 查询与发现：即时查询（
query）、范围查询（range_query）、标签名/值获取（label_names/label_values）、序列查询（series）、元数据获取（metric_metadata/targets_metadata） - 告警与规则：获取告警列表（
list_alerts）、规则列表（list_rules）、Alertmanager 集群信息（alertmanagers） - 系统与配置：读取运行配置（
config）、启动参数（flags）、构建信息（build_info）、运行时信息（runtime_info）、就绪与健康检查（ready/healthy） - TSDB 管理（需显式启用）：热重载（
reload）、优雅退出（quit）、清理 Tombstones、删除序列、创建快照、TSDB 统计、WAL 回放状态 - 知识库与文档：通过
docs_list、docs_read、docs_search工具让 LLM 查阅 Prometheus 官方文档 - Token 效率优化：TOON 编码将 JSON 输出转为 Token-Oriented Object Notation 格式；响应截断支持全局默认及工具级行数/条目上限
- 安全与管控：工具白名单（
--mcp.tools）；HTTP 配置文件连接带 Basic Auth/TLS 的 Prometheus；Web 配置文件保护自身端点
架构设计#
项目采用标准 Go 布局，cmd/prometheus-mcp-server/ 为主入口，internal/ 存放内部实现，pkg/ 存放可复用包，独立维护 charts/（Helm OCI）、packaging/systemd/（系统包）及 grafana/（预置 Dashboard）。
支持 Stdio（本地 CLI 直连）与 Streamable HTTP（含 SSE，容器化/远程部署）双传输协议。通过 --prometheus.backend 注入不同后端实现，各后端可动态增删工具集——例如 Thanos 后端移除 config/quit 并增加 list_stores。通过 .gitmodules 引入上游 prometheus/docs 仓库实现离线文档集成。自身暴露 Prometheus 指标并附带预构建 Grafana Dashboard，实现运行状态自观测。
部署方式#
二进制安装
prometheus-mcp-server --prometheus.url "https://your-prometheus:9090"
Docker
# Stdio
docker run --rm -i ghcr.io/tjhop/prometheus-mcp-server:latest \
--prometheus.url "https://your-prometheus:9090"
# HTTP
docker run --rm -p 8080:8080 ghcr.io/tjhop/prometheus-mcp-server:latest \
--prometheus.url "https://your-prometheus:9090" \
--mcp.transport "http" --web.listen-address ":8080"
Helm Chart (Kubernetes)
helm install prometheus-mcp-server oci://ghcr.io/tjhop/charts/prometheus-mcp-server \
--version <version> --set prometheus.url=http://prometheus:9090
systemd：提供系统级安装包，支持 apt install 后 systemctl enable --now 启动。
关键配置#
所有 CLI 参数均支持环境变量配置，前缀为 PROMETHEUS_MCP_SERVER_。
| 配置项 | CLI Flag | 说明 |
|---|---|---|
| 目标实例 | --prometheus.url | 指向 Prometheus 的地址 |
| 传输协议 | --mcp.transport | stdio（默认）或 http |
| 监听地址 | --web.listen-address | HTTP 模式监听端口 |
| 工具白名单 | --mcp.tools | 限制暴露给 LLM 的工具子集 |
| 后端类型 | --prometheus.backend | prometheus（默认）、thanos 等 |
| 危险操作 | --dangerous.enable-tsdb-admin-tools | 启用 TSDB 管理类工具 |
| 客户端认证 | --http.config | 连接后端 Prometheus 的 TLS/Auth 配置 |
| 服务端认证 | --web.config.file | MCP Server 自身 HTTP 端点安全配置 |
适用场景#
- LLM 辅助运维排障：让 Claude/Gemini/Ollama 等直接查询指标，诊断慢查询、分析实例健康状态
- SLO/Recording Rule 建议：LLM 分析指标后自动建议 Prometheus 记录规则
- Prometheus 最佳实践咨询：LLM 内置文档知识，可回答 metric/label 命名规范
- 多后端查询：在 Thanos 等兼容系统上执行 PromQL
- CI/CD 与 GitOps：通过 MCP 协议将可观测性集成到 AI 编码助手和自动化流程中
项目采用 Apache-2.0 许可证，由 tjhop 开发维护。