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.

Demos and Examples

Investigate metrics produced by the MCP server itself and suggest recording rules for SLOs

The prompt used was:

use the tools from the prometheus mcp server to investigate the metrics from the mcp server and suggest prometheus recording rules for SLOs

Summarize Prometheus metric/label naming best practices

The prompt used was:

summarize prometheus metric/label name best practices

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

Tools

Full Tool List

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
docs_search	Search the markdown files 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

Tool Sets

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. By default, they are all registered and available for use (TSDB Admin API tools need an extra flag).

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. The following 'core' tools are always loaded: [docs_list, docs_read, docs_search, query, range_query, metric_metadata, label_names, label_values, series]. Additional tools can be specified with the --mcp.tools flag.

For example, the command line:

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

Would result in the following tools being loaded:

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

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. Please see 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 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

# Streamable HTTP transport (capable of SSE as well)
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

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 or environment variables
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.

Telemetry

Metrics

Once running, the server exposes Prometheus metrics on the configured listen address and telemetry path (:8080/metrics, by default). Please see Flags for more information on how to change the listening interface, port, or telemetry path.

Metric name	Type	Description	Labels
prom_mcp_build_info	Gauge	A metric with a constant '1' value with labels for version, commit and build_date from which prometheus-mcp-server was built.	version, commit, build_date, goversion
prom_mcp_server_ready	Gauge	Info metric with a static '1' if the MCP server is ready, and '0' otherwise.
prom_mcp_api_calls_failed_total	Counter	Total number of Prometheus API failures, per endpoint.	target_path
prom_mcp_api_call_duration_seconds	Histogram	Duration of Prometheus API calls, per endpoint, in seconds.	target_path
prom_mcp_tool_calls_failed_total	Counter	Total number of failures per tool.	tool_name
prom_mcp_tool_call_duration_seconds	Histogram	Duration of tool calls, per tool, in seconds.	tool_name
prom_mcp_resource_calls_failed_total	Counter	Total number of failures per resource.	resource_uri
prom_mcp_resource_call_duration_seconds	Histogram	Duration of resource calls, per resource, in seconds.	resource_uri
go_*	Gauge/Counter	Standard Go runtime metrics from the client_golang library.
process_*	Gauge/Counter	Standard process metrics from the client_golang library.

Logs

This project makes heavy use of structured, leveled logging. Please see Flags for more information on how to set the log format, level, and optional file.

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:gpt-oss:20b), run export OLLAMA_MODEL="ollama:your_model" to override it before running make .

Requires MCP Inpsector to be installed:

make inspector

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.

make gemini

Manual Setup

Required software:

• Working Go environment
• Docker for local tests/linting/image building/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
  submodules                     ensure git submodules are initialized and updated
  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
  container                      build container images with goreleaser, alias for `build-all`
  image                          build container images with goreleaser, alias for `build-all`
  test                           run tests
  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_MCP_SERVER_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`, `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_SERVER_MCP_TOOLS)
      --prometheus.url="http://127.0.0.1:9090"
                                 URL of the Prometheus instance to connect to ($PROMETHEUS_MCP_SERVER_PROMETHEUS_URL)
      --http.config=HTTP.CONFIG  Path to config file to set Prometheus HTTP client options ($PROMETHEUS_MCP_SERVER_HTTP_CONFIG)
      --web.telemetry-path="/metrics"
                                 Path under which to expose metrics. ($PROMETHEUS_MCP_SERVER_WEB_TELEMETRY_PATH)
      --web.max-requests=40      Maximum number of parallel scrape requests. Use 0 to disable. ($PROMETHEUS_MCP_SERVER_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_SERVER_DANGEROUS_ENABLE_TSDB_ADMIN_TOOLS)
      --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_SERVER_LOG_FILE)
      --mcp.transport="stdio"    The type of transport to use for the MCP server [`stdio`, `http`]. ($PROMETHEUS_MCP_SERVER_MCP_TRANSPORT)
      --[no-]web.systemd-socket  Use systemd socket activation listeners instead of port listeners (Linux only). ($PROMETHEUS_MCP_SERVER_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_SERVER_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_SERVER_WEB_CONFIG_FILE)
      --log.level=info           Only log messages with the given severity or above. One of: [debug, info, warn, error] ($PROMETHEUS_MCP_SERVER_LOG_LEVEL)
      --log.format=logfmt        Output format of log messages. One of: [logfmt, json] ($PROMETHEUS_MCP_SERVER_LOG_FORMAT)
      --[no-]version             Show application version. ($PROMETHEUS_MCP_SERVER_VERSION)