Prometheus MCP Server

Prometheus MCP 服务

关于

这是一个 MCP 服务，可让大模型通过 API 与正在运行的 Prometheus 实例交互，执行生成和运行 promql 查询、列出和分析指标等操作。

演示与示例

请 Claude 调查查询缓慢的问题

使用的提示词是：

查询我的指标很慢，你能帮我找出原因吗？

调查 MCP 服务自身生成的指标，并为 SLO 提出记录规则

使用的提示词是：

使用 prometheus mcp 服务提供的工具调查 mcp 服务的指标，并为 SLO 提出 prometheus 记录规则

总结 Prometheus 指标／标签命名最佳实践

使用的提示词是：

总结 prometheus 指标／标签名称的最佳实践

报告为 prometheus.demo.prometheus.io 提供支持的 Prometheus 实例的运行状况

使用的提示词是：

请全面检查并总结 prometheus 服务端。 检查其配置、标志、运行时／构建信息以及其他你认为 有助于了解 prometheus 实例状态的内容， 包括分析指标和执行查询

工具

Prometheus HTTP API 会输出 JSON 数据，而此 MCP 服务中的工具会将这些 JSON 返回给大模型处理，因为 JSON 结构化清晰，且大模型能够很好地理解。

大模型与 Token／上下文效率

此 MCP 服务支持以下选项，有助于减少 Token／上下文用量：

TOON 编码

如果你关注 Token／上下文用量，此 MCP 服务还支持将 API 的 JSON 数据转换为 Token-Oriented Object Notation（TOON）格式。 虽然无法保证一定能减少 Token 用量，但这种格式的设计考虑了 Token 效率。 正如 TOON 文档中所述，它适用于结构统一的对象数组；对于非统一／复杂对象，JSON 可能仍然更节省 Token。 实际 Token 用量取决于使用模式，请查看常见工作流，以确定 TOON 输出是否有益。 有关可用标志及其对应环境变量的更多信息，请参阅标志。

API 响应截断

此功能允许你设置 Prometheus API 返回的行数或条目数上限，这有助于减少发送给大模型的数据量。 将上限设为 0 可禁用截断。 默认情况下，截断处于禁用状态。 请注意，能够处理工具请求参数的大模型可以针对受支持的工具，在每次工具调用时覆盖此全局截断上限。 有关可用标志及其对应环境变量的详细信息，请参阅 标志。

完整工具列表

注意：

由于 TSDB 管理 API 端点 允许执行删除数据等可能造成破坏的操作，因此默认情况下不会启用。要启用 TSDB 管理 API 端点，必须在启动 MCP 服务时使用标志 --dangerous.enable-tsdb-admin-tools，以确认你了解这些端点带来的相关风险。

工具集

该服务提供了许多用于与 Prometheus 交互的工具。这些工具既可通过 API 与 Prometheus 交互，也可用于执行读取文档等操作。 默认情况下，所有工具都会注册并可供使用（TSDB Admin API 工具需要额外的标志）。

为照顾上下文窗口较小的大模型，可以传入特定工具白名单，以便仅向服务注册这些工具。 以下“核心”工具始终会加载：[docs_list, docs_read, docs_search, runbooks_list, runbooks_read, query, range_query, metric_metadata, label_names, label_values, series]。 可以使用 --mcp.tools 标志指定其他工具。

例如，以下命令：

prometheus-mcp --mcp.tools=build_info --mcp.tools=flags --mcp.tools=runtime_info

会加载以下工具：

• build_info
• docs_list
• docs_read
• docs_search
• flags
• label_names
• label_values
• metric_metadata
• query
• range_query
• runbooks_list
• runbooks_read
• runtime_info
• series

Runbook（Agent 技能）和提示词

该服务内置了一组 runbook：针对常见 Prometheus 任务的引导式工作流，以该服务的工具为基础编写。每个 runbook 都会引导模型了解相关工具，然后通过示例查询建议可探索的主题，而不是规定固定的步骤顺序。 Runbook 涵盖系统健康检查、缺失数据排查、错误率调查、高基数优化、记录规则和告警规则审查，以及配置和性能调优等任务。

每个 runbook 都打包为完整的 Agent 技能：一个包含带有 name/description 前置元数据的 SKILL.md 的目录。 Runbook 通过以下三种方式提供：

• 工具：当请求符合某个 runbook 的用途时，模型可以通过 runbooks_list/runbooks_read 工具自行发现并读取。工具是可移植性最高的方式，适用于所有 MCP 客户端。
• 技能资源：根据 SEP-2640 技能扩展草案，每个 runbook 都是一个 skill://<name>/SKILL.md 资源，并由众所周知的 skill://index.json 发现索引列出；该服务还声明了 io.modelcontextprotocol/skills 扩展能力。支持技能的宿主可以像使用本地文件系统技能一样使用这些资源；其他客户端仍可将其作为普通 MCP 资源读取。
• MCP 提示词：每个 runbook 也会以其技能名称（例如 check-system-health、optimize-high-cardinality）注册为 MCP 提示词，因此支持提示词的客户端可以直接调用引导式工作流（通常会显示为斜杠命令）。

Prometheus 兼容后端

有许多 Prometheus 兼容后端可用于以各种方式扩展 prometheus，通常旨在提供长期存储，或聚合多个 prometheus 实例的查询结果。 一些示例可在 prometheus 文档的 远程存储 中找到。

其中许多服务还提供“prometheus 兼容” API，可使用原生 promQL 查询数据或与数据交互。 通常，此 MCP 服务至少应适用于其他 Prometheus API 兼容服务，以执行查询并与 series/labels/metadata 端点交互，从而发现指标和标签。 除此之外，不同系统会根据自身需求实现 API 的不同部分或扩展，因此 API 可能存在差异。

示例：

• Thanos 不使用集中式配置，因此未实现配置端点，并移除了配置工具。
• Mimir 和 Cortex 实现了额外的端点，用于管理、添加和移除规则

为解决这一问题，并在一些常用的 Prometheus 兼容系统上提供更好的体验，本项目可能会为部分系统添加直接支持，以提供不同或更多工具。 可以通过 --prometheus.backend flag 选择特定的 prometheus 后端实现。 特定版本 MCP 服务可用的后端实现列表，可通过 --help flag 的输出查看。 资格要求和支持标准仍在讨论中；如需请求支持特定后端或功能，请提出 issue，以便进一步讨论。

Prometheus 后端实现差异

资源

安装和使用

将此 MCP 服务与工具链全面集成，和／或将其安装为其他系统的工具服务，才能充分发挥其作用。 安装流程和集成支持因所用工具而异。 例如：

• 有些系统只能与 MCP 工具交互，无法与资源／提示词交互
• 有些系统使用 mcp.json 配置文件格式来管理 MCP 服务，有些则需要自定义格式
• 有些系统不直接支持 MCP，需要使用 mcp-to-openapi 等工具进行代理

请查阅所用或集成工具的文档，了解具体说明和支持程度。

传输方式

此服务通过 stdio（默认方式）或 HTTP（--mcp.transport=http，在 Web 监听地址的 /mcp 提供服务）使用 MCP。 支持 2024-11-05 至 2026-07-28 的 MCP 协议修订版，由客户端选择使用哪个版本。 HTTP 仅提供 Streamable HTTP 传输方式，不提供较旧的 HTTP+SSE 传输方式。

HTTP 传输是无状态的：每个请求都会单独处理，不会跟踪会话，因此副本可以置于任意负载均衡器后，无需会话保持。 由此可知：

• 仅提供 POST。有些客户端会打开的独立 GET 流会返回 405 Method Not Allowed，这不会造成影响：服务发送的所有内容都通过请求的响应传回。
• 保活 ping（--mcp.keepalive-interval）仅通过 stdio 发送；HTTP 没有可 ping 的会话。
• 在当前 MCP 修订版中，客户端在调用过程中断开连接会取消正在执行的 Prometheus 查询；较旧客户端的调用则会运行至完成。
• --mcp.session-timeout 已弃用且会被忽略。

--mcp.enable-client-logging 会将工具处理程序发出的日志行作为 MCP 日志通知转发给客户端，同时保留常规日志输出。 MCP 已弃用此功能。在弃用期内，该功能仍会继续工作，但客户端收到的内容取决于客户端：较新的客户端必须请求日志级别，而通过 HTTP 连接的较旧客户端会收到 info 及以上级别的日志。

二进制文件

从 Releases 页面下载适用于您系统的版本。 以下命令适用于 v0.19.0 及更高版本；较早版本请参阅下方的升级说明。 有关可用标志及其对应环境变量的更多信息，请参阅 Flags。

/path/to/prometheus-mcp <flags>

# or using env vars
PROMETHEUS_MCP_PROMETHEUS_URL="https://$yourPrometheus:9090" /path/to/prometheus-mcp

从 v0.18.0 或更早版本升级：自 v0.19.0 起，二进制文件名为 prometheus-mcp（此前为 prometheus-mcp-server），其环境变量前缀也从 PROMETHEUS_MCP_SERVER_ 改为 PROMETHEUS_MCP_。 旧变量名会被忽略且不会报错，因此升级时请重命名这些变量。

Docker

有关可用标志及其对应环境变量的更多信息，请参阅 Flags。

# Stdio transport
docker run --rm -i ghcr.io/tjhop/prometheus-mcp-server:latest --prometheus.url "https://$yourPrometheus:9090" 

# or using env vars
docker run --rm -i -e PROMETHEUS_MCP_SERVER_PROMETHEUS_URL="https://$yourPrometheus:9090" ghcr.io/tjhop/prometheus-mcp-server:latest

# HTTP transport
docker run --rm -p 8080:8080 ghcr.io/tjhop/prometheus-mcp-server:latest --prometheus.url "https://$yourPrometheus:9090" --mcp.transport "http" --web.listen-address ":8080"

# or using env vars
docker run --rm -p 8080:8080 -e PROMETHEUS_MCP_SERVER_PROMETHEUS_URL="https://$yourPrometheus:9090" -e PROMETHEUS_MCP_SERVER_MCP_TRANSPORT="http" -e PROMETHEUS_MCP_SERVER_WEB_LISTEN_ADDRESS=":8080" ghcr.io/tjhop/prometheus-mcp-server:latest

Helm Chart（Kubernetes）

提供了一个 Helm chart，可用于部署到 Kubernetes。该 chart 会在每次发布时以 OCI 制品的形式发布。

helm install prometheus-mcp-server oci://ghcr.io/tjhop/charts/prometheus-mcp-server \
  --version <version> \
  --set prometheus.url=http://prometheus:9090

完整的配置值列表和示例，请参阅 chart README。

Kubernetes（原始清单）

如果您希望不使用 Helm 进行部署，可参考以下 Kubernetes 清单示例：

• Kubernetes 部署
• OpenShift 部署

带 Systemd 的压缩包

从 Releases 页面下载适用于你系统的最新发行版压缩包。压缩包包含二进制文件和 Systemd 服务文件。 该服务单元会在 :8080 上运行 HTTP 传输，并使用默认的 --prometheus.url（http://127.0.0.1:9090）；如需设置其他标志，请在覆盖配置中通过对应的环境变量设置，例如 Environment=PROMETHEUS_MCP_PROMETHEUS_URL=https://prometheus.example.com:9090。

# extract the tarball and install the binary and unit file
# (<version> has no leading `v`, e.g. prometheus-mcp-0.19.0.linux-amd64.tar.gz)
tar -xzf prometheus-mcp-<version>.<os>-<arch>.tar.gz
cd prometheus-mcp-<version>.<os>-<arch>
install -m 0755 prometheus-mcp /usr/bin/prometheus-mcp
install -m 0644 prometheus-mcp.service /etc/systemd/system/
# create unit override and set any needed environment variables
systemctl edit prometheus-mcp.service
systemctl enable --now prometheus-mcp.service

注意：从 v0.19.0 起，发行版不再包含系统软件包（deb、rpm 或 Arch Linux .pkg.tar.zst）；请改用压缩包。 v0.18.0 及更早版本的软件包仍可在对应的发行页面获取。

安全与身份验证

连接到安全的 Prometheus 实例

MCP 服务支持使用 Prometheus HTTP config 文件连接到启用了安全保护的 Prometheus 实例。 此处的示例文件夹中提供了一个配置示例。 使用 --http.config 命令行标志指定 HTTP 配置文件。 如果无法读取该文件或文件无效，服务会在启动时退出，而不会回退到未进行身份验证的客户端。 更多信息请参阅 标志。

转发客户端凭据

使用 HTTP 传输时，MCP 服务会将每个 MCP 请求中的 Authorization 标头转发给 Prometheus，用于该请求的 API 调用。 不携带 Authorization 标头的请求，以及所有通过 stdio 传输的请求，都会使用根据标志构建的默认客户端（请参阅连接到安全的 Prometheus 实例）。

服务会原样转发客户端凭据给 Prometheus，不会对其进行验证。 不包含身份验证方案的凭据会作为 Bearer 令牌发送。 任何能够访问 MCP 端点的人，都至少可以使用默认客户端的凭据查询 Prometheus，因此请使用网页配置文件或网络级控制措施限制对端点的访问。 请注意，网页配置文件中的基本身份验证（basic_auth_users）会与凭据转发冲突：客户端用于向 MCP 服务进行身份验证的同一个 Authorization 标头，随后会被转发给 Prometheus，取代默认客户端的凭据。 仅使用 TLS 的网页配置不会使用 Authorization 标头，因此不受影响。

保护 MCP 服务端点

MCP 服务支持 Prometheus Web Configuration 文件，可通过可选的基本身份验证和自定义 TLS 配置公开其端点。 使用 --web.config.file 命令行标志指定 HTTP 配置文件。 更多信息请参阅标志。

遥测

健康检查端点

Web 服务会在配置的监听地址上公开健康检查端点，遵循 Prometheus 生态系统中通用的 /-/healthy 和 /-/ready 约定：

这些端点可直接用作 Kubernetes 存活和就绪探针。prom_mcp_server_ready 指标会报告相同的就绪状态。

指标

服务器启动后，会在配置的监听地址和遥测路径（默认为 :8080/metrics）上提供 Prometheus 指标。 有关如何更改监听接口、端口或遥测路径的更多信息，请参阅 标志。

Grafana 仪表板

grafana/ 目录中包含预构建的 Grafana 仪表板，可用于可视化 MCP 服务公开的指标。将仪表板 json 导入 grafana 后即可使用。

日志

本项目大量使用结构化、分级日志记录。 有关如何设置日志格式、级别和可选日志文件的更多信息，请参阅 标志。

MCP go-sdk 使用自己的日志记录器输出日志：其警告和错误会在默认级别显示，而每个请求的会话记录仅在使用 --log.level=debug 时显示。

开发

使用 Devbox + Direnv 配置开发环境

如果你使用 Devbox 和 Direnv，只需进入仓库目录， 即可设置所需的软件。

使用 Ollama 运行本地 LLM

参见 mcp.json，了解供工具使用的 MCP 配置示例。 需要安装 ollama。

注意：

若要覆盖默认 LLM（ollama:gpt-oss:20b），请在运行 make 前执行 export OLLAMA_MODEL="ollama:your_model" 进行覆盖。

make inspector

make mcphost

使用 gemini-cli 和 Gemini

参见 settings.json，了解使用 gemini-cli 运行 prometheus-mcp 的配置文件示例。 需要安装 gemini-cli。

make gemini

构建

本项目使用标准的 Prometheus 构建工具：promu， 通过 Makefile / Makefile.common 调用。二进制文件会嵌入一份固定版本的 prometheus/docs 快照，构建目标会自动下载并解压该快照 （固定版本记录在 Makefile 的 DOCS_VERSION 中）。

make build       # build the binary for the host platform (via promu)
make test        # run the test suite
make crossbuild  # build binaries for all release platforms
make             # run the full check suite: style, license, yamllint, lint, build, test

项目专用的辅助目标（Helm 打包和本地 LLM 客户端集成） 可通过 make help 查看：

make help

Usage:
  make <target>

Project targets:
  help                           print this help message (see Makefile.common for the standard prometheus targets)
  docs                           download and extract the pinned prometheus/docs snapshot for embedding
  helm-sync-dashboards           copy grafana dashboards into helm chart for packaging
  helm-lint                      run helm chart linting
  helm-template                  render helm templates for inspection
  helm-test                      install helm chart and run tests (requires a running cluster)
  mcphost                        use mcphost to run the prometheus-mcp against a local ollama model
  inspector                      use inspector to run the prometheus-mcp in STDIO transport mode
  inspector-http                 use inspector to run the prometheus-mcp in streamable HTTP transport mode
  open-webui                     use open-webui to run the prometheus-mcp
  gemini                         use gemini-cli to run the prometheus-mcp against Google Gemini models

命令行标志

可用的命令行标志记录在帮助标志中：

~/go/src/github.com/prometheus/prometheus-mcp (main [ ]) -> ./prometheus-mcp --help
usage: prometheus-mcp [<flags>]


Flags:
  -h, --[no-]help                Show context-sensitive help (also
                                 try --help-long and --help-man).
                                 ($PROMETHEUS_MCP_HELP)
      --mcp.tools=all ...        List of mcp tools to load. The target
                                 `all` can be used to load all tools.
                                 The target `core` loads only the core tools:
                                 docs_list,docs_read,docs_search,runbooks_list,runbooks_read,query,range_query,metric_metadata,label_names,label_values,series
                                 Otherwise, it is treated as an allow-list
                                 of tools to load, in addition to the core
                                 tools. Please see project README for more
                                 information and the full list of tools.
                                 ($PROMETHEUS_MCP_MCP_TOOLS)
      --[no-]mcp.enable-toon-output  
                                 Enable Token-Oriented Object Notation
                                 (TOON) output for tools instead of JSON
                                 ($PROMETHEUS_MCP_MCP_ENABLE_TOON_OUTPUT)
      --[no-]mcp.enable-client-logging  
                                 Enable sending log messages to connected
                                 MCP clients as protocol notifications.
                                 When enabled, tool execution logs are
                                 sent both to the server's primary
                                 log output and to the MCP client,
                                 allowing LLMs to observe server activity.
                                 ($PROMETHEUS_MCP_MCP_ENABLE_CLIENT_LOGGING)
      --mcp.transport="stdio"    The type of transport to use for
                                 the MCP server [`stdio`, `http`].
                                 ($PROMETHEUS_MCP_MCP_TRANSPORT)
      --prometheus.backend=PROMETHEUS.BACKEND  
                                 Customize the toolset for a specific
                                 Prometheus API compatible backend.
                                 Supported backends include: prometheus,thanos
                                 ($PROMETHEUS_MCP_PROMETHEUS_BACKEND)
      --prometheus.url="http://127.0.0.1:9090"  
                                 URL of the Prometheus instance to connect to
                                 ($PROMETHEUS_MCP_PROMETHEUS_URL)
      --prometheus.timeout=1m    Timeout for API calls to the Prometheus backend
                                 ($PROMETHEUS_MCP_PROMETHEUS_TIMEOUT)
      --prometheus.truncation-limit=0  
                                 If enabled, this controls the maximum query
                                 response size in number of lines/entries
                                 provided to the LLM from the API response.
                                 LLMs can override truncation limits if
                                 needed on a per-tool-call basis via tool
                                 request arguments on supported tools.
                                 To disable truncation limits, set to 0.
                                 ($PROMETHEUS_MCP_PROMETHEUS_TRUNCATION_LIMIT)
      --http.config=HTTP.CONFIG  Path to config file to set Prometheus HTTP
                                 client options ($PROMETHEUS_MCP_HTTP_CONFIG)
      --web.telemetry-path="/metrics"  
                                 Path under which to expose metrics.
                                 ($PROMETHEUS_MCP_WEB_TELEMETRY_PATH)
      --web.max-requests=40      Maximum number of parallel scrape
                                 requests. Use 0 to disable.
                                 ($PROMETHEUS_MCP_WEB_MAX_REQUESTS)
      --[no-]dangerous.enable-tsdb-admin-tools  
                                 Enable and allow using tools that access
                                 Prometheus' TSDB Admin API endpoints
                                 (`snapshot`, `delete_series`, and
                                 `clean_tombstones` tools). This is dangerous,
                                 and allows for destructive operations
                                 like deleting data. It is not the fault
                                 of this MCP server if the LLM you're
                                 connected to nukes all your data. Docs:
                                 https://prometheus.io/docs/prometheus/latest/querying/api/#tsdb-admin-apis
                                 ($PROMETHEUS_MCP_DANGEROUS_ENABLE_TSDB_ADMIN_TOOLS)
      --mcp.keepalive-interval=30s  
                                 Interval between keepalive pings on
                                 the stdio transport; the session is
                                 closed when the peer stops answering.
                                 Not used by the HTTP transport.
                                 ($PROMETHEUS_MCP_MCP_KEEPALIVE_INTERVAL)
      --mcp.session-timeout=10m  Deprecated and ignored: HTTP is served
                                 statelessly. Will be removed in a future
                                 release. ($PROMETHEUS_MCP_MCP_SESSION_TIMEOUT)
      --[no-]docs.auto-update    Enable automatic documentation updates
                                 from the official prometheus/docs
                                 repository. Checks every 24h0m0s.
                                 ($PROMETHEUS_MCP_DOCS_AUTO_UPDATE)
      --log.file=LOG.FILE        The name of the file to log to (file
                                 rotation policies should be configured
                                 with external tools like logrotate)
                                 ($PROMETHEUS_MCP_LOG_FILE)
      --[no-]web.systemd-socket  Use systemd socket activation listeners
                                 instead of port listeners (Linux only).
                                 ($PROMETHEUS_MCP_WEB_SYSTEMD_SOCKET)
      --web.listen-address=:8080 ...  
                                 Addresses on which to expose metrics and
                                 web interface. Repeatable for multiple
                                 addresses. Examples: `:9100` or `[::1]:9100`
                                 for http, `vsock://:9100` for vsock
                                 ($PROMETHEUS_MCP_WEB_LISTEN_ADDRESS)
      --web.config.file=""       Path to configuration file that can
                                 enable TLS or authentication. See:
                                 https://github.com/prometheus/exporter-toolkit/blob/master/docs/web-configuration.md
                                 ($PROMETHEUS_MCP_WEB_CONFIG_FILE)
      --log.level=info           Only log messages with the given severity
                                 or above. One of: [debug, info, warn, error]
                                 ($PROMETHEUS_MCP_LOG_LEVEL)
      --log.format=logfmt        Output format of log messages. One of: [logfmt,
                                 json] ($PROMETHEUS_MCP_LOG_FORMAT)
      --[no-]version             Show application version.
                                 ($PROMETHEUS_MCP_VERSION)