Prometheus MCP server: 28 tools at 85 tokens each

The leanest tool definitions measured here, a nine-tool core profile, and the five default tools that can stop a server or delete series.

Last verified 1 September 2026 · from The Prometheus repository, its release binaries and the server's own tools/list response

This page is one of 90 in a directory of monitoring and developer tools. Each page checks what an AI coding agent can get out of the tool through its MCP server, the connector that lets the agent query the tool directly.

What is the Prometheus MCP server?

It is the Prometheus project's server for the Model Context Protocol. A connected agent can run PromQL, read metric metadata and inspect alerting rules without leaving the editor.

Two tools stand out from the rest. docs_search searches the markdown documentation from the prometheus/docs repository, so an agent can look up PromQL syntax from inside the same connection it queries with.

The server also carries a core profile of nine tools: docs_list, docs_read, docs_search, query, range_query, metric_metadata, label_names, label_values and series. Selecting it costs a fraction of an already small list.

Prometheus sits squarely in production observability and reaches nothing in code review, CI, agent observability or cost.

For an agent, that means Prometheus answers numeric questions about running systems and nothing else. It can find which series moved and when an alert fired. It has no logs to read and no trace to follow, so it pairs with a logs or tracing connector for an investigation.

What can an AI agent do with Prometheus?

The core profile covers the first three rows with nine tools, so it is the cheaper starting point when metric work is all you need.

What connecting costs before the first question

A context window is the amount of text a model can hold at once, and connecting uses some of it before the agent asks anything. Every tool the server registers sends its name, description and input schema to the model when the session starts. The tool list is charged whether or not a single tool is called.

28 tools cost between 2,349 and 4,483 tokens, which is about 85 tokens per tool. That is the leanest ratio measured in this guide, and it holds across a mid-sized tool count rather than a tiny one.

Brevity is the reason. Descriptions average 71 characters and schemas average 255, against 3,271-character descriptions on the Weights & Biases server and 2,143-character schemas on Rootly's.

Encodings: GPT-5.6, GPT-5.5 o200k_base; GPT-4, GPT-3.5 cl100k_base; Claude Haiku 4.5 to Opus 5 count_tokens. Counted 24 August 2026 from tools/list on the released v0.18.0 macOS binary. It was run locally against the default target.

Registration is static, so no Prometheus instance answered. Figures cover name, description and input schema.

The two models in column one share the o200k_base encoding, so they get one count. The spread is formatting, about 47%. Reasoning tokens are output, spent per request. The tool list is input, charged once at connection.

The Claude figures are measured rather than encoded. Anthropic publishes no local tokenizer. So the definitions were sent to the API's count_tokens endpoint, and a no-tools baseline was subtracted. The range covers two tokenizer generations rather than two serializations. Haiku 4.5 and Opus 4.6 sit at the low end. Opus 5 and Sonnet 5 sit at the high end. The gap between them is about a quarter.

Prometheus MCP server limits: where answers come back incomplete

Two of the limits below are about what the server can do to Prometheus, and one is about what an empty result means.

How to configure Prometheus MCP for agents

1. 1

   Start with --mcp.tools=core

   Nine tools cover querying, metadata and documentation, and leave the administrative group unregistered.

2. 2

   Know what --dangerous.enable-tsdb-admin-tools does

   It gates execution of the TSDB admin endpoints. The tools are registered and visible either way. Capturing tools/list with and without it returned the same names.

3. 3

   Point the server at the right instance

   --prometheus.url defaults to http://127.0.0.1:9090, so an unconfigured server silently targets a local Prometheus.

4. 4

   Cap response size on wide queries

   --prometheus.truncation-limit bounds how many lines reach the model, which matters on high-cardinality series.

Paste this into your agent’s instructions

A PromQL answer looks exact, and an empty result from a down target looks identical to a genuine zero. The block makes the agent show the query.

When you answer using Prometheus MCP tools, state:
- The exact PromQL you ran and the time range it covered.
- Whether you checked list_targets. A missing metric is often
  a target that stopped being scraped.
- Whether you called snapshot, delete_series, clean_tombstones,
  reload or quit. These change or stop the server.
Never state that data does not exist. State that no series
matched the query above.
Write your answer in ASD-STE100 Simplified Technical
English. Use short sentences with one idea in each.

Do you need the MCP server at all?

Yes, for metric work. At 2,349 tokens the tool definitions cost less than a single long query result, so the usual argument against connecting does not apply here.

The HTTP API remains the right choice inside a script or a dashboard, where a fixed query is repeated and no model is involved.

Grafana's server is the alternative when the question spans metrics, logs and dashboards, because Grafana reaches Prometheus as one datasource among several.

Connect this server for metric work. Reach for Grafana when the question crosses from metrics into logs.

Prometheus MCP server setup

Download the release binary for your platform from the v0.18.0 release, or install the .deb, .rpm or Arch package. There is nothing to configure for a local Prometheus on the default port.

The transport defaults to stdio. --mcp.transport=http serves the same tools over HTTP for a shared deployment.

claude mcp add-json "prometheus" '{"command":
  "prometheus-mcp-server",
  "args":["--mcp.tools=core",
          "--prometheus.url=http://localhost:9090"]}'

{"mcpServers":{"prometheus":{
  "command":"prometheus-mcp-server",
  "args":["--mcp.tools=core",
          "--prometheus.url=https://prom.internal"]}}}

[mcp_servers.prometheus]
command = "prometheus-mcp-server"
args = ["--mcp.tools=core",
        "--prometheus.url=http://localhost:9090"]

Every other client

Each block below is the configuration for one client, with the file path and the key that client expects.

{"mcpServers":{"prometheus":{"command":"prometheus-mcp-server",
  "args":["--mcp.tools=core","--prometheus.url=https://prom.internal"]}}}

{"mcpServers":{"prometheus":{"command":"prometheus-mcp-server",
  "args":["--mcp.tools=core","--prometheus.url=https://prom.internal"]}}}

{"servers":{"prometheus":{"command":"prometheus-mcp-server",
  "args":["--mcp.tools=core","--prometheus.url=https://prom.internal"]}}}

{"mcpServers":{"prometheus":{"command":"prometheus-mcp-server",
  "args":["--mcp.tools=core","--prometheus.url=https://prom.internal"]}}}

prometheus-mcp-server \
  --mcp.transport=http \
  --mcp.tools=core \
  --prometheus.url=https://prom.internal

prometheus-mcp-server --prometheus.backend=thanos \
  --prometheus.url=https://thanos.internal

Read-only access, permissions and security

• Five administrative tools are in the default list

  snapshot, delete_series, clean_tombstones, reload and quit are all registered on a bare connection.

• quit shuts Prometheus down

  Its own description calls it a management endpoint that triggers a graceful shutdown.

• delete_series writes tombstones

  Its description requires both a start and an end time specifically to prevent accidental deletion of all data.

• The dangerous flag gates execution, not visibility

  Capturing tools/list with and without --dangerous.enable-tsdb-admin-tools returned the same 28 names, so a model sees the administrative tools either way.

• config returns the loaded configuration

  Scrape configurations often name internal hosts and job labels you would not otherwise send to a model.

Troubleshooting

Every query returns nothing

The server defaults to http://127.0.0.1:9090. If your Prometheus is elsewhere, pass --prometheus.url or set PROMETHEUS_MCP_SERVER_PROMETHEUS_URL.

A metric that should exist is missing

Check list_targets before concluding anything. A target that stopped being scraped produces the same empty result as a metric that was never emitted.

A label query floods the context

High-cardinality labels return large lists. Set --prometheus.truncation-limit to bound how many entries reach the model.

Prometheus stopped

quit is registered by default and triggers a graceful shutdown. Run with --mcp.tools=core, which does not include it.

Prometheus MCP server: Reference

What engineers report

This is the Prometheus project's own server, with 19 releases since the repository was created on 2 May 2025. The counts below describe that repository, which changed hands and changed name.

“I'm experiencing context overflow when calling list_rules because standard Kubernetes rule templates contain a very large number of elements. The response size exceeds the LLM's context window capacity.”

“There are no options to configure security access to the MCP server itself. This is especially important when running in SSE/HTTP transport modes.”

Repository facts from the GitHub API, retrieved 24 August 2026. The repository was transferred into the prometheus organization and now resolves to prometheus/prometheus-mcp; older links redirect. Tool counts come from the server's own tools/list response on the released binary.

Should you connect an agent to Prometheus?

Yes. Best for running with --mcp.tools=core unless you specifically need the administrative tools.

Strongest fit

Anyone running Prometheus who wants an agent to write PromQL against it without a browser.

Main advantage

The leanest cost per tool measured in this guide, with a nine-tool core profile that is cheaper still.

Main weakness

Metrics only. No logs and no traces, so an investigation needs a second connector.

Operational risk

Shutdown, reload and series deletion are registered on a bare connection, visible to the model either way.

Frequently asked questions