Prometheus MCP Server

About

This is an MCP server to allow LLMs to interact with a running Prometheus instance via the API to do things like generate and execute promql queries, list and analyze metrics, etc.

Here is a screen recording using Google Gemini models to report on the health of the Prometheus instance that powers prometheus.demo.prometheus.io/. The prompt used was:

please provide a comprehensive review and summary of the prometheus server. review it's configuration, flags, runtime/build info, and anything else that you feel may provide insight into the status of the prometheus instance, including analyzing metrics and executing queries

⚠️ NOTE: I used yolo mode in the demo to auto-accept tool usage. You probably shouldn't do this. Please read/understand/approve your tool usage, don't just let the LLM go wild. That's how you end up with robot overlords.

Tools

Tool Name	Description
alertmanagers	Get overview of Prometheus Alertmanager discovery
build_info	Get Prometheus build information
config	Get Prometheus configuration
docs_list	List of Official Prometheus Documentation Files
docs_read	Read the named markdown file containing official Prometheus documentation from the prometheus/docs repo
exemplars_query	Performs a query for exemplars by the given query and time range
flags	Get runtime flags
label_names	Returns the unique label names present in the block in sorted order by given time range and matchers
label_values	Performs a query for the values of the given label, time range and matchers
list_alerts	List all active alerts
list_rules	List all alerting and recording rules that are loaded
list_targets	Get overview of Prometheus target discovery
metric_metadata	Returns metadata about metrics currently scraped by the metric name
query	Execute an instant query against the Prometheus datasource
range_query	Execute a range query against the Prometheus datasource
runtime_info	Get Prometheus runtime information
series	Finds series by label matchers
targets_metadata	Returns metadata about metrics currently scraped by the target
tsdb_stats	Get usage and cardinality statistics from the TSDB
wal_replay_status	Get current WAL replay status

NOTE:

Because the TSDB Admin API endpoints allow for potentially destructive operations like deleting data, they are not enabled by default. In order to enable the TSDB Admin API endpoints, the MCP server must be started with the flag --dangerous.enable-tsdb-admin-tools to acknowledge the associated risk these endpoints carry.

Tool Name	Description
clean_tombstones	Removes the deleted data from disk and cleans up the existing tombstones
delete_series	deletes data for a selection of series in a time range
snapshot	creates a snapshot of all current data into snapshots/- under the TSDB's data directory and returns the directory as response

Resources

Resource Name	Resource URI	Description
prometheus://list_metrics	List metrics available
prometheus://targets	Overview of the current state of the Prometheus target discovery
prometheus://tsdb_stats	Usage and cardinality statistics from the TSDB
prometheus://docs	List of official Prometheus Documentation files
prometheus://docs{/file*}	Read official Prometheus Documentation files by name

Prompts

Not implemented yet, to be determined

Installation and Usage

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.

Binary

Download a release appropriate for your system from the Releases page.

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

Docker

docker run -it --rm ghcr.io/tjhop/prometheus-mcp-server <flags>

System Packages

Download a release appropriate for your system from the Releases page. A Systemd service file is included in the system packages that are built.

# install system package (example assuming Debian based)
apt install /path/to/package
# create unit override, add any needed flags
systemctl edit prometheus-mcp-server.service
systemctl enable --now prometheus-mcp-server.service

Note: While packages are built for several systems, there are currently no plans to attempt to submit packages to upstream package repositories.

Development

Development Environment with Devbox + Direnv

If you use Devbox and Direnv, then simply entering the directory for the repo should set up the needed software.

Local LLM with Ollama

See mcp.json for an example MCP config for use with tooling. Requires ollama to be installed.

NOTE:

To override the default LLM (ollama:qwen2.5-coder:3b), run export OLLAMA_MODEL="ollama:your_model" to override it before running make .

Using MCP Inspector and a local ollama instance:

Requires MCP Inpsector to be installed:

make inspector

Using mcphost and a local ollama instance:

Requires mcphost to be installed:

make mcphost

Gemini with gemini-cli

See settings.json for an example config file to run gemini-cli with the prometheus-mcp-server. Requires gemini-cli to be installed.

Using `gemini-cli` and hosted models:

make gemini

Manual Setup

Required software:

• Working Go environment
• Podman for local tests/linting/etc
• GNU Make
• ollama
• mcp inspector
• mcphost

Building

The included Makefile has several targets to aid in development:

~/go/src/github.com/tjhop/prometheus-mcp-server (main [ ]) -> make

Usage:
  make <target>

Targets:
  help                           print this help message
  tidy                           tidy modules
  fmt                            apply go code style formatter
  lint                           run linters
  binary                         build a binary
  build                          alias for `binary`
  build-all                      test release process with goreleaser, does not publish/upload
  test                           run tests
  container                      build container image with binary
  image                          alias for `container`
  podman                         alias for `container`
  docker                         alias for `container`
  mcphost                        use mcphost to run the prometheus-mcp-server against a local ollama model
  inspector                      use inspector to run the prometheus-mcp-server in STDIO transport mode
  inspector-http                 use inspector to run the prometheus-mcp-server in streamable HTTP transport mode
  open-webui                     use open-webui to run the prometheus-mcp-server
  gemini                         use gemini-cli to run the prometheus-mcp-server against Google Gemini models

Command Line Flags

The available command line flags are documented in the help flag:

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


Flags:
  -h, --[no-]help                Show context-sensitive help (also try --help-long and --help-man).
      --prometheus.url="http://127.0.0.1:9090"  
                                 URL of the Prometheus instance to connect to
      --http.config=HTTP.CONFIG  Path to config file to set Prometheus HTTP client options
      --web.telemetry-path="/metrics"  
                                 Path under which to expose metrics.
      --web.max-requests=40      Maximum number of parallel scrape requests. Use 0 to disable.
      --[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
      --log.file=LOG.FILE        The name of the file to log to (file rotation policies should be configured with external tools like logrotate)
      --mcp.transport="stdio"    The type of transport to use for the MCP server [`stdio`, `http`].
      --[no-]web.systemd-socket  Use systemd socket activation listeners instead of port listeners (Linux only).
      --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
      --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
      --log.level=info           Only log messages with the given severity or above. One of: [debug, info, warn, error]
      --log.format=logfmt        Output format of log messages. One of: [logfmt, json]
      --[no-]version             Show application version.