Skip to content
Back to search

prometheus-mcp

MCP server for LLMs to interact with Prometheus

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/prometheus/prometheus-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/prometheus/prometheus-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/prometheus--prometheus-mcp/badge.svg)](/listings/prometheus--prometheus-mcp)

HTML

<a href="/listings/prometheus--prometheus-mcp"><img src="/api/listings/prometheus--prometheus-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

This MCP server is most useful when fully integrated with tooling and/or installed as a tool server with another system. Installation procedures and integration support will vary depending on the tools being used. For example: - some systems can only interact with MCP tools and not resources/prompts - some systems use mcp.json config file format to manage MCP servers and some require custom formats - some systems don't speak MCP directly and require tools like mcp-to-openapi to proxy

Please check the documentation for the tool being used/integrated for specific instructions and level of support.

Transports

The server speaks MCP over `stdio` (the default) or HTTP (`--mcp.transport=http`, served at `/mcp` on the web listen address). MCP protocol revisions `2024-11-05` through `2026-07-28` are supported, and the client chooses which one to use. Over HTTP, only the Streamable HTTP transport is served; the older HTTP+SSE transport is not.

The HTTP transport is stateless: each request is handled on its own and no session is tracked, so replicas can sit behind any load balancer without session affinity. What follows from that:

- Only `POST` is served. The standalone `GET` stream some clients open answers `405 Method Not Allowed`, which is harmless: everything the server sends rides the response to a request. - Keepalive pings (`--mcp.keepalive-interval`) are only sent on `stdio`; there is no session to ping over HTTP. - A client that disconnects mid-call cancels the in-flight Prometheus query on current MCP revisions; older clients' calls run to completion. - `--mcp.session-timeout` is deprecated and ignored.

`--mcp.enable-client-logging` forwards the log lines tool handlers emit to the client as MCP log notifications, in addition to the normal log output. MCP has deprecated this feature. It keeps working during the deprecation window, but what a client receives is up to the client: newer clients must ask for a log level, and older clients over HTTP get `info` and above.

Binary

Download a release appropriate for your system from the [Releases](https://github.com/tjhop/prometheus-mcp-server/releases) page. Please see [Flags](#command-line-flags) for more information on the available flags and their corresponding environment variables.

/path/to/prometheus-mcp-server <flags>

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

Docker

Please see [Flags](#command-line-flags) for more information on the available flags and their corresponding environment variables.

# 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)

A Helm chart is available for deploying to Kubernetes. The chart is published as an OCI artifact on each release.

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

See the [chart README](./charts/prometheus-mcp-server/README.md) for the full list of configuration values and examples.

Kubernetes (Raw Manifests)

If you prefer deploying without Helm, example Kubernetes manifests are available:

- [Kubernetes Deployment](./examples/k8s-deployment.yml)

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 585 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Prometheus MCP Server
  2. [![license](https://img.shields.io/github/license/prometheus/prometheus-mcp)](https://github.com/prometheus/prometheus-mcp/blob/main/LICENSE)
  3. [![golangci-lint](https://github.com/prometheus/prometheus-mcp/actions/workflows/golangci-lint.yml/badge.svg)](https://github.com/prometheus/prometheus-mcp/actions/workflows/golangci-lint.yml)
  4. [![Latest Release](https://img.shields.io/github/v/release/prometheus/prometheus-mcp)](https://github.com/prometheus/prometheus-mcp/releases/latest)
  5. [![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/prometheus/prometheus-mcp/total)](https://github.com/prometheus/prometheus-mcp/releases/latest)
  6. ![Prometheus MCP Server Logo](images/logo-small.png)
  7. ## About
  8. This is an [MCP](https://modelcontextprotocol.io/introduction) server to allow LLMs to interact with a running [Prometheus](https://prometheus.io/) instance via the API to do things like generate and execute promql queries, list and analyze metrics, etc.
  9. ### Demos and Examples
  10. #### Asking Claude to Investigate Slow Queries
  11. The prompt used was:
  12. > querying my metrics is slow, can you help me figure out why?
  13. [![Demo prompt to ask claude to investigate slow queries](images/claude_high_cardinality.gif)](https://asciinema.org/a/8KxZgJxrXXX2zjwwDRSP4UtqL)
  14. #### Investigate metrics produced by the MCP server itself and suggest recording rules for SLOs
  15. The prompt used was:
  16. > use the tools from the prometheus mcp server to investigate the metrics from
  17. > the mcp server and suggest prometheus recording rules for SLOs
  18. [![Demo prompt to investigate metrics produced by the MCP server and create rules for SLOs](images/gemini_slo.gif)](https://asciinema.org/a/av3WhfD122A1HHOq2d4SEZgMn)
  19. #### Summarize Prometheus metric/label naming best practices
  20. The prompt used was:
  21. > summarize prometheus metric/label name best practices
  22. [![Demo prompt to summarize prometheus metric and label name best practies](images/gemini_docs_search.gif)](https://asciinema.org/a/o9RKpCXBmBmG4zqhuFsvTHf2C)
  23. #### Report on the health of the Prometheus instance that powers prometheus.demo.prometheus.io
  24. The prompt used was:
  25. > please provide a comprehensive review and summary of the prometheus server.
  26. > review it's configuration, flags, runtime/build info, and anything else that
  27. > you feel may provide insight into the status of the prometheus instance,
  28. > including analyzing metrics and executing queries
  29. [![Demo prompt to review the health of the demo.prometheus.io prometheus instance](images/demo-usage-with-prometheus-demo-server.gif)](https://asciinema.org/a/733513)
  30. ### Tools
  31. The Prometheus HTTP API outputs JSON data, and the tools in this MCP server return that JSON to the LLM for processing as it's structured and well understood by LLMs.
  32. #### LLMs and Token/Context Efficiency
  33. This MCP server supports the following options which have the potential to reduce token/context usage:
  34. ##### TOON Encoding
  35. If token/context usage is a concern, this MCP server also supports converting the API's JSON data to the [Token-Oriented Object Notation (TOON) format](https://github.com/toon-format/toon).
  36. While it is not guaranteed to reduce token usage, it is designed with token efficiency in mind.
  37. As noted on TOON's documentation, it excels at uniform arrays of objects; non-uniform/complex objects may still be more token-efficient in JSON.
  38. Real world token usage will depend on usage patterns, please review common workflows to determine if TOON output may be beneficial.
  39. Please see [Flags](#command-line-flags) for more information on the available flags and their corresponding environment variables.
  40. ##### API Response Truncation
  41. This feature allows you to set a maximum limit on the number of lines or entries returned from the Prometheus API for, which can help in reducing the amount of data sent to the LLM.
  42. Setting the limit to `0` disables truncation.
  43. Truncation is disabled by default.
  44. Note that LLMs capable of handling tool request arguments can override this global truncation limit on a per-tool-call basis for supported tools.
  45. Please see [Flags](#command-line-flags) for more information on the available flags and their corresponding environment variables.
  46. #### Full Tool List
  47. | Tool Name | Description |
  48. | --- | --- |
  49. | `alertmanagers` | Get overview of Prometheus Alertmanager discovery |
  50. | `build_info` | Get Prometheus build information |
  51. | `config` | Get Prometheus configuration |
  52. | `docs_list` | List of Official Prometheus Documentation Files |
  53. | `docs_read` | Read the named markdown file containing official Prometheus documentation from the prometheus/docs repo |
  54. | `docs_search` | Search the markdown files containing official Prometheus documentation from the prometheus/docs repo |
  55. | `exemplar_query` | Performs a query for exemplars by the given query and time range |
  56. | `flags` | Get runtime flags |
  57. | `healthy` | Management API endpoint that can be used to check Prometheus health |
  58. | `label_names` | Returns the unique label names present in the block in sorted order by given time range and matchers |
  59. | `label_values` | Performs a query for the values of the given label, time range and matchers |
  60. | `list_alerts` | List all active alerts |
  61. | `list_rules` | List all alerting and recording rules that are loaded |
  62. | `list_targets` | Get overview of Prometheus target discovery |
  63. | `metric_metadata` | Returns metadata about metrics currently scraped by the metric name |
  64. | `query` | Execute an instant query against the Prometheus datasource, returning one value per series at a single point in time |
  65. | `quit` | Management API endpoint that can be used to trigger a graceful shutdown of Prometheus |
  66. | `range_query` | Execute a range query against the Prometheus datasource, returning values over a time window |
  67. | `ready` | Management API endpoint that can be used to check Prometheus is ready to serve traffic (i.e. respond to queries |
  68. | `reload` | Management API endpoint that can be used to trigger a reload of the Prometheus configuration and rule files |
  69. | `runbooks_list` | List the runbooks embedded in this server: guided workflows (Agent Skills) for common Prometheus tasks |
  70. | `runbooks_read` | Read the named runbook by skill name (e.g. `check-system-health`) |
  71. | `runtime_info` | Get Prometheus runtime information |
  72. | `series` | Finds series by label matchers |
  73. | `targets_metadata` | Returns metadata about metrics currently scraped by the target |
  74. | `tsdb_stats` | Get usage and cardinality statistics from the TSDB |
  75. | `wal_replay_status` | Get current WAL replay status |
  76. __NOTE:__
  77. > Because the [TSDB Admin API endpoints](https://prometheus.io/docs/prometheus/latest/querying/api/#tsdb-admin-apis)
  78. > allow for potentially destructive operations like deleting data, they are not
  79. > enabled by default. In order to enable the TSDB Admin API endpoints, the MCP
  80. > server must be started with the flag `--dangerous.enable-tsdb-admin-tools` to
  81. > acknowledge the associated risk these endpoints carry.
  82. | Tool Name | Description |
  83. | --- | --- |
  84. | `clean_tombstones` | Removes the deleted data from disk and cleans up the existing tombstones |
  85. | `delete_series` | deletes data for a selection of series in a time range |
  86. | `snapshot` | creates a snapshot of all current data into snapshots/<datetime>-<rand> under the TSDB's data directory and returns the directory as response |
  87. #### Tool Sets
  88. The server exposes many tools to interact with Prometheus. There are tools to interact with Prometheus via the API, as well as additional tools to do things like read documentation, etc.
  89. By default, they are all registered and available for use (TSDB Admin API tools need an extra flag).
  90. To be considerate to LLMs with smaller context windows, it's possible to pass in a whitelist of specific tools to register with the server.
  91. The following 'core' tools are always loaded: `[docs_list, docs_read, docs_search, runbooks_list, runbooks_read, query, range_query, metric_metadata, label_names, label_values, series]`.
  92. Additional tools can be specified with the [`--mcp.tools` flag](#command-line-flags).
  93. For example, the command line:
  94. ```shell
  95. prometheus-mcp --mcp.tools=build_info --mcp.tools=flags --mcp.tools=runtime_info
  96. ```
  97. Would result in the following tools being loaded:
  98. - `build_info`
  99. - `docs_list`
  100. - `docs_read`
  101. - `docs_search`
  102. - `flags`
  103. - `label_names`
  104. - `label_values`
  105. - `metric_metadata`
  106. - `query`
  107. - `range_query`
  108. - `runbooks_list`
  109. - `runbooks_read`
  110. - `runtime_info`
  111. - `series`
  112. #### Runbooks (Agent Skills) and Prompts
  113. The server embeds a set of runbooks: guided workflows for common Prometheus tasks, expressed in terms of the server's tools. Each runbook orients the model on the relevant tools, then suggests topics to explore with example queries rather than prescribing a fixed sequence of steps.
  114. Runbooks cover tasks like system health checks, missing-data triage, error-rate investigation, high-cardinality optimization, recording/alerting rule review, and configuration/performance tuning.
  115. Each runbook is packaged as a full [Agent Skill](https://agentskills.io/specification): a directory containing a `SKILL.md` with `name`/`description` frontmatter.
  116. Runbooks are exposed three ways:
  117. - **Tools**: the model can discover and read them itself via the `runbooks_list`/`runbooks_read` tools when a request matches a runbook's purpose. Tools are the most portable path and work in every MCP client.
  118. - **Skill resources**: per the [SEP-2640 skills extension draft](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2640), each runbook is a `skill://<name>/SKILL.md` resource, enumerated by the well-known `skill://index.json` discovery index, and the server declares the `io.modelcontextprotocol/skills` extension capability. Skill-aware hosts can consume these like local filesystem skills; other clients can still read them as ordinary MCP resources.
  119. - **MCP prompts**: each runbook is also registered as an [MCP prompt](https://modelcontextprotocol.io/docs/concepts/prompts) under its skill name (e.g. `check-system-health`, `optimize-high-cardinality`), so clients with prompt support can invoke a guided workflow directly (often surfaced as slash commands).
  120. #### Prometheus Compatible Backends
  121. There are many Prometheus compatible backends that can be used to extend prometheus in a variety of ways, often with the goals of offering long term storage or query aggregation from multiple prometheus instances.
  122. Some examples can be found in the [Remote Storage](https://prometheus.io/docs/operating/integrations/#remote-endpoints-and-storage) of prometheus' docs.
  123. Many of those services also offer a "prometheus compatible" API that can be used to query/interact with the data using native promQL.
  124. In general, this MCP server should at a minimum work for other prometheus API compatible services to execute queries and interact with the series/labels/metadata endpoints for metric and label discovery.
  125. Beyond that, there may be API differences as the different systems implement different parts/extensions of the API for their needs.
  126. Examples:
  127. - Thanos does not use a centralized config, so the config endpoint is not implemented and thus the config tool is removed.
  128. - Mimir and Cortex implement extra endpoints to manage/add/remove rules
  129. To workaround this and provide a better experience on some of the commonly used Prometheus compatible systems, this project may add direct support for select systems to provide different/more tools.
  130. Choosing a specific prometheus backend implementation can be done with the [`--prometheus.backend` flag](#command-line-flags).
  131. The list of available backend implementations on a given release of the MCP server can be found in the output of the [`--help` flag](#command-line-flags).
  132. Qualifications and support criteria are still under consideration, please open an issue to request support/features for a specific backend for further discussion.
  133. ##### Prometheus Backend Implementation Differences
  134. | Backend | Tool | Add/Remove/Change | Notes |
  135. | --- | --- | --- | --- |
  136. | `prometheus` | n/a | none | Standard prometheus tools. Functionally equivalent to `--mcp.tools="all"`. The default MCP server toolset. |
  137. | [`thanos`](https://thanos.io/) | `alertmanagers` | remove | Thanos does not implement the endpoint and the tool returns a `404`. |
  138. | [`thanos`](https://thanos.io/) | `clean_tombstones` | remove | Prometheus TSDB admin endpoint |
  139. | [`thanos`](https://thanos.io/) | `config` | remove | Thanos does not use a centralized config, so it doesn't implement the endpoint and the tool returns a `404`. |
  140. | [`thanos`](https://thanos.io/) | `delete_series` | remove | Prometheus TSDB admin endpoint |
  141. | [`thanos`](https://thanos.io/) | `list_stores` | add | Thanos provides an additional endpoint to list store API servers. |
  142. | [`thanos`](https://thanos.io/) | `quit` | remove | Thanos does not implement the endpoint and the tool returns a `404`. |
  143. | [`thanos`](https://thanos.io/) | `reload` | remove | Thanos does not implement the endpoint and the tool returns a `404`. |
  144. | [`thanos`](https://thanos.io/) | `snapshot` | remove | Prometheus TSDB admin endpoint |
  145. | [`thanos`](https://thanos.io/) | `targets_metadata` | remove | Thanos does not implement the endpoint and the tool returns a `404` ([thanos-io/thanos#7119](https://github.com/thanos-io/thanos/issues/7119)). |
  146. | [`thanos`](https://thanos.io/) | `wal_replay_status` | remove | Thanos does not implement the endpoint and the tool returns a `404`. |
  147. ### Resources
  148. | Resource Name | Resource URI | Description |
  149. | --- | --- | --- |
  150. | List of Official Prometheus Documentation Files | `prometheus://docs` | List of official Prometheus Documentation files |
  151. | Read Official Prometheus Documentation | `prometheus://docs/{+file}` | Read official Prometheus Documentation files by name |
  152. | Agent Skills Discovery Index | `skill://index.json` | [SEP-2640](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2640) discovery index of the embedded runbooks/skills |
  153. | Prometheus Runbook (Agent Skill) | `skill://<name>/SKILL.md` | Read the named runbook, packaged as an Agent Skill (one resource per runbook) |
  154. ## Installation and Usage
  155. This MCP server is most useful when fully integrated with tooling and/or installed as a tool server with another system.
  156. Installation procedures and integration support will vary depending on the tools being used.
  157. For example:
  158. - some systems can only interact with MCP tools and not resources/prompts
  159. - some systems use mcp.json config file format to manage MCP servers and some require custom formats
  160. - some systems don't speak MCP directly and require tools like mcp-to-openapi to proxy
  161. Please check the documentation for the tool being used/integrated for specific instructions and level of support.
  162. ### Transports
  163. The server speaks MCP over `stdio` (the default) or HTTP (`--mcp.transport=http`, served at `/mcp` on the web listen address).
  164. MCP protocol revisions `2024-11-05` through `2026-07-28` are supported, and the client chooses which one to use.
  165. Over HTTP, only the Streamable HTTP transport is served; the older HTTP+SSE transport is not.
  166. With `stdio`, the web listener is enabled by default. Set `--no-web.listen` (or `PROMETHEUS_MCP_WEB_LISTEN=false`) to disable it.
  167. This makes metrics, health and readiness endpoints, pprof, the landing page, and HTTP documentation unavailable; MCP documentation tools remain available.
  168. The HTTP transport is stateless: each request is handled on its own and no session is tracked, so replicas can sit behind any load balancer without session affinity.
  169. What follows from that:
  170. - Only `POST` is served. The standalone `GET` stream some clients open answers `405 Method Not Allowed`, which is harmless: everything the server sends rides the response to a request.
  171. - Keepalive pings (`--mcp.keepalive-interval`) are only sent on `stdio`; there is no session to ping over HTTP.
  172. - A client that disconnects mid-call cancels the in-flight Prometheus query on current MCP revisions; older clients' calls run to completion.
  173. - `--mcp.session-timeout` is deprecated and ignored.
  174. `--mcp.enable-client-logging` forwards the log lines tool handlers emit to the client as MCP log notifications, in addition to the normal log output.
  175. MCP has deprecated this feature. It keeps working during the deprecation window, but what a client receives is up to the client: newer clients must ask for a log level, and older clients over HTTP get `info` and above.
  176. ### Binary
  177. Download a release appropriate for your system from the [Releases](https://github.com/prometheus/prometheus-mcp/releases) page.
  178. The commands below are for v0.19.0 and later; see the upgrade note below for earlier releases.
  179. Please see [Flags](#command-line-flags) for more information on the available flags and their corresponding environment variables.
  180. ```shell
  181. /path/to/prometheus-mcp <flags>
  182. # or using env vars
  183. PROMETHEUS_MCP_PROMETHEUS_URL="https://$yourPrometheus:9090" /path/to/prometheus-mcp
  184. ```
  185. _Upgrading from v0.18.0 or earlier_: as of v0.19.0 the binary is named `prometheus-mcp` (previously `prometheus-mcp-server`), and its environment variables use the `PROMETHEUS_MCP_` prefix instead of `PROMETHEUS_MCP_SERVER_`.
  186. The old variable names are ignored without an error, so rename them when you upgrade.
  187. ### Docker
  188. Please see [Flags](#command-line-flags) for more information on the available flags and their corresponding environment variables.
  189. ```shell
  190. # Stdio transport
  191. docker run --rm -i ghcr.io/tjhop/prometheus-mcp-server:latest --prometheus.url "https://$yourPrometheus:9090"
  192. # or using env vars
  193. docker run --rm -i -e PROMETHEUS_MCP_SERVER_PROMETHEUS_URL="https://$yourPrometheus:9090" ghcr.io/tjhop/prometheus-mcp-server:latest
  194. ```
  195. ```shell
  196. # HTTP transport
  197. 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"
  198. # or using env vars
  199. 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
  200. ```
  201. ### Helm Chart (Kubernetes)
  202. A Helm chart is available for deploying to Kubernetes. The chart is published as an OCI artifact on each release.
  203. ```bash
  204. helm install prometheus-mcp-server oci://ghcr.io/tjhop/charts/prometheus-mcp-server \
  205. --version <version> \
  206. --set prometheus.url=http://prometheus:9090
  207. ```
  208. See the [chart README](./charts/prometheus-mcp-server/README.md) for the full list of configuration values and examples.
  209. ### Kubernetes (Raw Manifests)
  210. If you prefer deploying without Helm, example Kubernetes manifests are available:
  211. - [Kubernetes Deployment](./examples/k8s-deployment.yml)
  212. - [OpenShift Deployment](./examples/openshift-deployment.yml)
  213. ### Tarball with Systemd
  214. Download the latest release tarball for your system from the [Releases](https://github.com/prometheus/prometheus-mcp/releases) page. Tarballs include the binary and a Systemd service file.
  215. The unit runs the HTTP transport on `:8080` against the default `--prometheus.url` (`http://127.0.0.1:9090`); set other flags through their environment variables in the override, for example `Environment=PROMETHEUS_MCP_PROMETHEUS_URL=https://prometheus.example.com:9090`.
  216. ```shell
  217. # extract the tarball and install the binary and unit file
  218. # (<version> has no leading `v`, e.g. prometheus-mcp-0.19.0.linux-amd64.tar.gz)
  219. tar -xzf prometheus-mcp-<version>.<os>-<arch>.tar.gz
  220. cd prometheus-mcp-<version>.<os>-<arch>
  221. install -m 0755 prometheus-mcp /usr/bin/prometheus-mcp
  222. install -m 0644 prometheus-mcp.service /etc/systemd/system/
  223. # create unit override and set any needed environment variables
  224. systemctl edit prometheus-mcp.service
  225. systemctl enable --now prometheus-mcp.service
  226. ```
  227. _Note_: As of v0.19.0, releases no longer include system packages (deb, rpm, or Arch Linux `.pkg.tar.zst`); use the tarball instead.
  228. Packages for v0.18.0 and earlier remain available on their release pages.
  229. ## Security and Authentication
  230. ### Connecting to Secure Prometheus Instances
  231. The MCP server supports [Prometheus HTTP config](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#http_config) files to connect to secured Prometheus instances.
  232. An example config can be found [in the examples folder here](./examples/http-config.yml).
  233. Use the `--http.config` command-line flag to provide an HTTP configuration file.
  234. If the file cannot be read or is invalid, the server exits at startup instead of falling back to an unauthenticated client.
  235. Please see [Flags](#command-line-flags) for more information.
  236. ### Forwarding Client Credentials
  237. When using the HTTP transport, the MCP server forwards the `Authorization` header on each MCP request to Prometheus for that request's API calls.
  238. Requests that carry no `Authorization` header, and all requests over the stdio transport, use the default client built from flags (see [Connecting to Secure Prometheus Instances](#connecting-to-secure-prometheus-instances)).
  239. The server forwards client credentials to Prometheus as-is and does not validate them.
  240. A credential that does not include an auth scheme is sent as a `Bearer` token.
  241. Anyone who can reach the MCP endpoint can query Prometheus with at least the default client's credentials, so restrict access to the endpoint with a [web configuration file](#securing-the-mcp-server-endpoints) or network-level controls.
  242. Note that basic authentication in the web configuration file (`basic_auth_users`) conflicts with credential forwarding: the same `Authorization` header a client uses to authenticate to the MCP server is then forwarded to Prometheus in place of the default client's credentials.
  243. TLS-only web configurations do not use the `Authorization` header and are unaffected.
  244. ### Securing the MCP Server Endpoints
  245. The MCP server supports [Prometheus Web Configuration files](https://github.com/prometheus/exporter-toolkit/blob/master/docs/web-configuration.md) files to expose it's endpoints behind optional basic auth and custom TLS configs.
  246. Use the `--web.config.file` command-line flag to provide an HTTP configuration file.
  247. Please see [Flags](#command-line-flags) for more information.
  248. ## Telemetry
  249. ### Health Endpoints
  250. The web server exposes health endpoints on the configured listen address, following the `/-/healthy` and `/-/ready` convention used across the Prometheus ecosystem:
  251. | Endpoint | Description |
  252. | --- | --- |
  253. | `/-/healthy` | Liveness: always returns `200 OK` while the process is up and serving HTTP. |
  254. | `/-/ready` | Readiness: returns `200 OK` once the MCP transport is mounted and able to accept client sessions, and `503 Service Unavailable` before that and during shutdown. |
  255. These map directly onto Kubernetes liveness/readiness probes. The `prom_mcp_server_ready` metric reports the same readiness state.
  256. ### Metrics
  257. Unless `--no-web.listen` is set, the server exposes Prometheus metrics on the configured listen address and telemetry path (`:8080/metrics`, by default).
  258. Please see [Flags](#command-line-flags) for more information on how to change the listening interface, port, or telemetry path.
  259. <details>
  260. <summary>Prometheus MCP Server Metrics</summary>
  261. | Metric name | Type | Description | Labels |
  262. | --- | --- | --- | --- |
  263. | `prom_mcp_build_info` | `Gauge` | A metric with a constant '1' value with labels for version, commit and build_date from which prometheus-mcp was built. | `version`, `commit`, `build_date`, `goversion` |
  264. | `prom_mcp_server_ready` | `Gauge` | Info metric with a static '1' if the MCP server is ready, and '0' otherwise. | |
  265. | `prom_mcp_api_calls_failed_total` | `Counter` | Total number of Prometheus API failures, per endpoint. | `target_path` |
  266. | `prom_mcp_api_call_duration_seconds` | `Histogram` | Duration of Prometheus API calls, per endpoint, in seconds. | `target_path` |
  267. | `prom_mcp_tool_calls_failed_total` | `Counter` | Total number of failures per tool. Calls canceled by the client are not counted. | `tool_name` |
  268. | `prom_mcp_tool_call_duration_seconds` | `Histogram` | Duration of tool calls, per tool, in seconds. | `tool_name` |
  269. | `prom_mcp_resource_calls_failed_total` | `Counter` | Total number of failures per resource. | `resource_uri` |
  270. | `prom_mcp_resource_call_duration_seconds` | `Histogram` | Duration of resource calls, per resource, in seconds. | `resource_uri` |
  271. | `prom_mcp_docs_last_update_timestamp_seconds` | `Gauge` | Unix timestamp of last successful docs auto-update. | |
  272. | `prom_mcp_docs_update_failures_total` | `Counter` | Total number of docs auto-update failures. | |
  273. | `go_*` | `Gauge`/`Counter` | Standard Go runtime metrics from the `client_golang` library. | |
  274. | `process_*` | `Gauge`/`Counter` | Standard process metrics from the `client_golang` library. | |
  275. </details>
  276. ### Grafana Dashboard
  277. A pre-built [Grafana](https://grafana.com/) dashboard is included in the [`grafana/`](./grafana/) directory for visualizing the metrics exposed by the MCP server. Import the dashboard json into grafana and it should be ready to go.
  278. ### Logs
  279. This project makes heavy use of structured, leveled logging.
  280. Please see [Flags](#command-line-flags) for more information on how to set the log format, level, and optional file.
  281. The MCP go-sdk logs through a logger of its own: its warnings and errors show at the default level, and its per-request session bookkeeping only with `--log.level=debug`.
  282. ## Development
  283. ### Development Environment with Devbox + Direnv
  284. If you use [Devbox](https://www.jetify.com/devbox) and
  285. [Direnv](https://direnv.net/), then simply entering the directory for the repo
  286. should set up the needed software.
  287. ### Local LLM with Ollama
  288. See [`mcp.json`](./examples/mcp.json) for an example MCP config for use with tooling.
  289. Requires [`ollama`](https://github.com/ollama/ollama) to be installed.
  290. _NOTE:_
  291. > To override the default LLM (`ollama:gpt-oss:20b`), run `export
  292. > OLLAMA_MODEL="ollama:your_model"` to override it before running `make` .
  293. <details>
  294. <summary>Using MCP Inspector and a local ollama instance:</summary>
  295. Requires [MCP Inpsector](https://github.com/modelcontextprotocol/inspector) to be installed:
  296. ```bash
  297. make inspector
  298. ```
  299. </details>
  300. <details>
  301. <summary>Using mcphost and a local ollama instance:</summary>
  302. Requires [`mcphost`](https://github.com/mark3labs/mcphost) to be installed:
  303. ```bash
  304. make mcphost
  305. ```
  306. </details>
  307. ### Gemini with gemini-cli
  308. See [`settings.json`](./examples/.gemini/settings.json) for an example config file to run gemini-cli with prometheus-mcp.
  309. Requires [gemini-cli](https://github.com/google-gemini/gemini-cli) to be installed.
  310. <details>
  311. <summary>Using `gemini-cli` and hosted models:</summary>
  312. ```bash
  313. make gemini
  314. ```
  315. </details>
  316. ### Manual Setup
  317. Required software:
  318. - Working Go environment
  319. - Docker for local tests/linting/image building/etc
  320. - GNU Make
  321. - [ollama](https://github.com/ollama/ollama)
  322. - [mcp inspector](https://github.com/modelcontextprotocol/inspector)
  323. - [mcphost](https://github.com/mark3labs/mcphost)
  324. ### Building
  325. This project uses the standard Prometheus build tooling: [`promu`](https://github.com/prometheus/promu)
  326. driven through `Makefile` / `Makefile.common`. The binary embeds a pinned
  327. snapshot of `prometheus/docs`, which the build targets download and extract
  328. automatically (the pin lives in `DOCS_VERSION` in the `Makefile`).
  329. ```bash
  330. make build # build the binary for the host platform (via promu)
  331. make test # run the test suite
  332. make crossbuild # build binaries for all release platforms
  333. make # run the full check suite: style, license, yamllint, lint, build, test
  334. ```
  335. Project-specific helper targets (helm packaging and the local LLM client
  336. integrations) are listed by `make help`:
  337. ```bash
  338. make help
  339. Usage:
  340. make <target>
  341. Project targets:
  342. help print this help message (see Makefile.common for the standard prometheus targets)
  343. docs download and extract the pinned prometheus/docs snapshot for embedding
  344. helm-sync-dashboards copy grafana dashboards into helm chart for packaging
  345. helm-lint run helm chart linting
  346. helm-template render helm templates for inspection
  347. helm-test install helm chart and run tests (requires a running cluster)
  348. mcphost use mcphost to run the prometheus-mcp against a local ollama model
  349. inspector use inspector to run the prometheus-mcp in STDIO transport mode
  350. inspector-http use inspector to run the prometheus-mcp in streamable HTTP transport mode
  351. open-webui use open-webui to run the prometheus-mcp
  352. gemini use gemini-cli to run the prometheus-mcp against Google Gemini models
  353. ```
  354. ## Command Line Flags
  355. The available command line flags are documented in the help flag:
  356. ```bash
  357. ~/go/src/github.com/prometheus/prometheus-mcp (main [ ]) -> ./prometheus-mcp --help
  358. usage: prometheus-mcp [<flags>]
  359. Flags:
  360. -h, --[no-]help Show context-sensitive help (also
  361. try --help-long and --help-man).
  362. ($PROMETHEUS_MCP_HELP)
  363. --mcp.tools=all ... List of mcp tools to load. The target
  364. `all` can be used to load all tools.
  365. The target `core` loads only the core tools:
  366. docs_list,docs_read,docs_search,runbooks_list,runbooks_read,query,range_query,metric_metadata,label_names,label_values,series
  367. Otherwise, it is treated as an allow-list
  368. of tools to load, in addition to the core
  369. tools. Please see project README for more
  370. information and the full list of tools.
  371. ($PROMETHEUS_MCP_MCP_TOOLS)
  372. --[no-]mcp.enable-toon-output
  373. Enable Token-Oriented Object Notation
  374. (TOON) output for tools instead of JSON
  375. ($PROMETHEUS_MCP_MCP_ENABLE_TOON_OUTPUT)
  376. --[no-]mcp.enable-client-logging
  377. Enable sending log messages to connected
  378. MCP clients as protocol notifications.
  379. When enabled, tool execution logs are
  380. sent both to the server's primary
  381. log output and to the MCP client,
  382. allowing LLMs to observe server activity.
  383. ($PROMETHEUS_MCP_MCP_ENABLE_CLIENT_LOGGING)
  384. --mcp.transport="stdio" The type of transport to use for
  385. the MCP server [`stdio`, `http`].
  386. ($PROMETHEUS_MCP_MCP_TRANSPORT)
  387. --prometheus.backend=PROMETHEUS.BACKEND
  388. Customize the toolset for a specific
  389. Prometheus API compatible backend.
  390. Supported backends include: prometheus,thanos
  391. ($PROMETHEUS_MCP_PROMETHEUS_BACKEND)
  392. --prometheus.url="http://127.0.0.1:9090"
  393. URL of the Prometheus instance to connect to
  394. ($PROMETHEUS_MCP_PROMETHEUS_URL)
  395. --prometheus.timeout=1m Timeout for API calls to the Prometheus backend
  396. ($PROMETHEUS_MCP_PROMETHEUS_TIMEOUT)
  397. --prometheus.truncation-limit=0
  398. If enabled, this controls the maximum query
  399. response size in number of lines/entries
  400. provided to the LLM from the API response.
  401. LLMs can override truncation limits if
  402. needed on a per-tool-call basis via tool
  403. request arguments on supported tools.
  404. To disable truncation limits, set to 0.
  405. ($PROMETHEUS_MCP_PROMETHEUS_TRUNCATION_LIMIT)
  406. --http.config=HTTP.CONFIG Path to config file to set Prometheus HTTP
  407. client options ($PROMETHEUS_MCP_HTTP_CONFIG)
  408. --[no-]web.listen Enable the web listener.
  409. ($PROMETHEUS_MCP_WEB_LISTEN)
  410. --web.telemetry-path="/metrics"
  411. Path under which to expose metrics.
  412. ($PROMETHEUS_MCP_WEB_TELEMETRY_PATH)
  413. --web.max-requests=40 Maximum number of parallel scrape
  414. requests. Use 0 to disable.
  415. ($PROMETHEUS_MCP_WEB_MAX_REQUESTS)
  416. --[no-]dangerous.enable-tsdb-admin-tools
  417. Enable and allow using tools that access
  418. Prometheus' TSDB Admin API endpoints
  419. (`snapshot`, `delete_series`, and
  420. `clean_tombstones` tools). This is dangerous,
  421. and allows for destructive operations
  422. like deleting data. It is not the fault
  423. of this MCP server if the LLM you're
  424. connected to nukes all your data. Docs:
  425. https://prometheus.io/docs/prometheus/latest/querying/api/#tsdb-admin-apis
  426. ($PROMETHEUS_MCP_DANGEROUS_ENABLE_TSDB_ADMIN_TOOLS)
  427. --mcp.keepalive-interval=30s
  428. Interval between keepalive pings on
  429. the stdio transport; the session is
  430. closed when the peer stops answering.
  431. Not used by the HTTP transport.
  432. ($PROMETHEUS_MCP_MCP_KEEPALIVE_INTERVAL)
  433. --mcp.session-timeout=10m Deprecated and ignored: HTTP is served
  434. statelessly. Will be removed in a future
  435. release. ($PROMETHEUS_MCP_MCP_SESSION_TIMEOUT)
  436. --[no-]docs.auto-update Enable automatic documentation updates
  437. from the official prometheus/docs
  438. repository. Checks every 24h0m0s.
  439. ($PROMETHEUS_MCP_DOCS_AUTO_UPDATE)
  440. --log.file=LOG.FILE The name of the file to log to (file
  441. rotation policies should be configured
  442. with external tools like logrotate)
  443. ($PROMETHEUS_MCP_LOG_FILE)
  444. --[no-]web.systemd-socket Use systemd socket activation listeners
  445. instead of port listeners (Linux only).
  446. ($PROMETHEUS_MCP_WEB_SYSTEMD_SOCKET)
  447. --web.listen-address=:8080 ...
  448. Addresses on which to expose metrics and
  449. web interface. Repeatable for multiple
  450. addresses. Examples: `:9100` or `[::1]:9100`
  451. for http, `vsock://:9100` for vsock
  452. ($PROMETHEUS_MCP_WEB_LISTEN_ADDRESS)
  453. --web.config.file="" Path to configuration file that can
  454. enable TLS or authentication. See:
  455. https://github.com/prometheus/exporter-toolkit/blob/master/docs/web-configuration.md
  456. ($PROMETHEUS_MCP_WEB_CONFIG_FILE)
  457. --log.level=info Only log messages with the given severity
  458. or above. One of: [debug, info, warn, error]
  459. ($PROMETHEUS_MCP_LOG_LEVEL)
  460. --log.format=logfmt Output format of log messages. One of: [logfmt,
  461. json] ($PROMETHEUS_MCP_LOG_FORMAT)
  462. --[no-]version Show application version.
  463. ($PROMETHEUS_MCP_VERSION)
  464. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.