Prometheus MCP Server Cursor IDE Setup 2026 (PromQL for Agents)

How do you connect Prometheus to Cursor? Add a prometheus entry to mcp.json that runs pab1it0/prometheus-mcp-server — via Docker (ghcr.io/pab1it0/prometheus-mcp-server:latest) or a local pip/uvx install — with a PROMETHEUS_URL environment variable pointed at your Prometheus instance. If your Prometheus is behind auth, add PROMETHEUS_USERNAME/PROMETHEUS_PASSWORD for basic auth or PROMETHEUS_TOKEN for a bearer token. Restart Cursor, confirm the green dot, then ask it to run a PromQL query as a first test.

This server is community-maintained (not a Prometheus project or CNCF release), read-only by design — every tool it exposes queries or lists metrics, none of them write — and it's a fit for anyone already running Grafana, Datadog, or Honeycomb dashboards who wants an agent able to answer "what's this metric doing right now" without leaving the editor.

Quick reference

Prerequisites

Step 1: Pick an install method

Docker (recommended — no local Python environment to manage):

docker run -i --rm \
  -e PROMETHEUS_URL="http://your-prometheus:9090" \
  ghcr.io/pab1it0/prometheus-mcp-server:latest

Kubernetes, via Helm — if Prometheus itself lives in-cluster and you'd rather deploy the MCP server alongside it:

helm install prometheus-mcp-server \
  oci://ghcr.io/pab1it0/charts/prometheus-mcp-server \
  --version 1.1.1 \
  --set prometheus.url="http://prometheus:9090"

pip/uvx, if you'd rather run it as a local process without Docker — install prometheus-mcp-server from PyPI and point Cursor's command at the installed executable instead of docker.

Step 2: Add it to Cursor's mcp.json

The Docker path is the one most setups reach for first:

{
  "mcpServers": {
    "prometheus": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "PROMETHEUS_URL",
        "ghcr.io/pab1it0/prometheus-mcp-server:latest"
      ],
      "env": {
        "PROMETHEUS_URL": "http://your-prometheus:9090"
      }
    }
  }
}

Save to ~/.cursor/mcp.json (available in every project) or .cursor/mcp.json (this project only), restart Cursor, and check Settings → Tools & Integrations → MCP Tools for a green dot next to prometheus.

Step 3: Authenticate against a protected Prometheus

Most production Prometheus deployments sit behind some form of auth in front of the raw query API — a reverse proxy, an ingress with basic auth, or an mTLS-secured Mimir/Cortex gateway. The server supports all three patterns via extra environment variables in the same env block:

Basic auth:

"env": {
  "PROMETHEUS_URL": "https://your-prometheus:9090",
  "PROMETHEUS_USERNAME": "your-username",
  "PROMETHEUS_PASSWORD": "your-password"
}

Bearer token:

"env": {
  "PROMETHEUS_URL": "https://your-prometheus:9090",
  "PROMETHEUS_TOKEN": "your-bearer-token"
}

mTLS client certificate:

"env": {
  "PROMETHEUS_URL": "https://your-prometheus:9090",
  "PROMETHEUS_CLIENT_CERT": "/path/to/client.crt",
  "PROMETHEUS_CLIENT_KEY": "/path/to/client.key"
}

If you're on Docker, remember every env var referenced in env also needs a matching -e VARNAME flag in args — the Docker CLI doesn't automatically forward everything in env into the container unless it's named explicitly, which is the shape of the base config above.

There's also PROMETHEUS_URL_SSL_VERIFY, which disables TLS certificate verification. Use it only against a Prometheus instance with a self-signed cert on a network you control — disabling verification against anything reachable from the open internet defeats the point of using HTTPS at all.

Step 4: Verify the connection

Ask Cursor something that requires a real PromQL round-trip:

Run a PromQL query against Prometheus for the current value of up and tell me which targets are down.

or

What's the 5-minute rate of http_requests_total over the last hour?

A real answer with actual metric values confirms PROMETHEUS_URL and auth are correct. An empty or error response usually means the URL, port, or credentials are wrong — check the troubleshooting section below.

The six tools it exposes

Everything here reads; nothing writes or deletes. There's no tool that touches alerting rules, recording rules, or Prometheus configuration — if you need an agent to reason about alert definitions, that still means opening the YAML directly or reaching for a filesystem MCP server pointed at your rules files.

Multi-tenant setups: ORG_ID and TOOL_PREFIX

If your "Prometheus" is actually a multi-tenant backend like Grafana Mimir or Cortex, queries need a tenant identifier attached. Set ORG_ID in the same env block to scope every query the MCP server makes to your tenant:

"env": {
  "PROMETHEUS_URL": "https://your-mimir-gateway:9090",
  "ORG_ID": "your-tenant-id"
}

TOOL_PREFIX is a separate, unrelated option — it prefixes the tool names themselves (e.g., prom_execute_query instead of execute_query), which matters if you're running two instances of this server against two different Prometheus backends in the same Cursor config and need the agent to tell their tools apart.

Common mistakes

Using execute_query when you meant execute_range_query. An instant query returns one value at one timestamp. If you ask Cursor for "the last hour of CPU usage" and it only calls execute_query, you'll get a single number, not a trend — the range tool is the one that takes a time window and step interval.

Forgetting the port. PROMETHEUS_URL needs the full http://host:9090 (or whatever port your instance listens on) — a bare hostname without a port is a common copy-paste mistake from a URL that's normally reached through a reverse proxy on port 443.

Setting PROMETHEUS_URL_SSL_VERIFY to disable checks against a public endpoint. This flag exists for self-signed certs on internal networks, not as a general fix for "the connection isn't working" — leaving it on against anything internet-facing removes a real security control.

Expecting write access. There's no tool here for silencing alerts, editing recording rules, or pushing metrics. This server is a read path only, by design.

Troubleshooting

Server shows connected but every query errors. Run health_check first — if that also fails, the problem is network reachability or the URL itself, not a specific PromQL query. Confirm you can reach PROMETHEUS_URL from the same machine Cursor (or the Docker container) runs on.

401/403 from Prometheus. Confirm you're using the right auth mode for your setup — basic auth env vars won't help if your proxy actually expects a bearer token, and vice versa. Check what your reverse proxy or gateway actually enforces, not what you assume it does.

Docker container can't resolve your-prometheus hostname. localhost inside a Docker container refers to the container itself, not your host machine. If Prometheus runs on the same host as Docker, use host.docker.internal (Mac/Windows) or the host's LAN IP (Linux) instead of localhost in PROMETHEUS_URL.

Queries against Mimir/Cortex return no data despite health_check passing. Missing ORG_ID is the most common cause — multi-tenant backends silently scope to a default or empty tenant if it's absent, rather than erroring outright.

Range query times out on a large window. A execute_range_query over months of data at a fine step interval can return an enormous payload. Narrow the time window or widen the step before assuming the server itself is broken.

Related guides

Frequently Asked Questions

Is there an official Prometheus MCP server? No — Prometheus itself doesn't ship an MCP server. pab1it0/prometheus-mcp-server is a community-maintained implementation distributed via Docker (ghcr.io/pab1it0/prometheus-mcp-server), PyPI, and a Helm chart for Kubernetes.

Can this server modify alerting rules or Prometheus config? No. All six exposed tools are read-only — queries, metric listing, metadata, and target health. There's no write path for alerts, recording rules, or configuration.

Does it work with Grafana Mimir or Cortex instead of vanilla Prometheus? Yes, since they expose the same PromQL query API. Multi-tenant backends additionally need the ORG_ID environment variable set, or queries silently scope to a default tenant.

What's the difference between execute_query and execute_range_query? execute_query runs an instant PromQL query and returns one value per series at a single point in time. execute_range_query runs the same kind of query over a time window with a step interval, returning a series suitable for trend analysis.

How do I authenticate against a Prometheus behind basic auth or a bearer token? Set PROMETHEUS_USERNAME/PROMETHEUS_PASSWORD for basic auth, or PROMETHEUS_TOKEN for a bearer token, alongside PROMETHEUS_URL in the same env block. mTLS client certs are also supported via PROMETHEUS_CLIENT_CERT and PROMETHEUS_CLIENT_KEY.

Official docs cited