home / mcp / prometheus mcp server

Prometheus MCP Server

Provides read-only Prometheus queries, alerts, targets, and metadata for AI-assisted analysis and anomaly detection.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "arktechnwa-prometheus-mcp": {
      "command": "prometheus-mcp",
      "args": [
        "--config",
        "/path/to/config.json"
      ],
      "env": {
        "PROM_CONFIG": "YOUR_CONFIG_JSON_PATH"
      }
    }
  }
}

Prometheus MCP enables read-only access to your Prometheus data for AI-assisted analysis. You can query current values, time ranges, alerts, targets, metadata, and more, all without mutating any state. It surfaces metrics and human-friendly summaries to help you understand health and performance at a glance.

How to use

You use an MCP client to connect to the Prometheus MCP server and run a set of prepared commands. Start by configuring the MCP with your Prometheus endpoint and optional authentication. From there, you can execute instant queries, range queries, and metadata lookups, as well as fetch alert status, target health, and rule sets. Use the AI-assisted analysis tools to interpret metrics, detect anomalies, and suggest PromQL expressions for deeper insights. All operations are read-only by design, so you won’t mutate any data on the Prometheus server.

Key capabilities include: getting current values and ranges, discovering metrics and labels, inspecting alert status and history, and retrieving metric metadata. For AI-assisted workflows, you can ask questions like whether a metric looks normal, what caused a spike, or request a suggested query for a given scenario. These patterns help you quickly understand system health without manually composing every PromQL expression.

How to install

Prerequisites: you need Node.js 18 or newer and a running Prometheus server (2.x+). Optionally, you can enable a fallback AI with an API key.

Install the MCP package globally so you can run the Prometheus MCP server from the command line.

npm install -g @arktechnwa/prometheus-mcp

Additional configuration and usage notes

Configuration is managed through a JSON file that specifies how to connect to Prometheus, what permissions to grant, and safety limits for queries. You can customize timeouts, cardinality safeguards, and which features are enabled. You can also enable a fallback AI haiku feature for lightweight anomaly cues.

A representative configuration snippet for connecting to Prometheus and enabling basic permissions is shown here for reference in your own setup. You would place this in your config.json as the MCP server reads it.

{
  "prometheus": {
    "url": "http://localhost:9090",
    "auth": {
      "type": "none"
    }
  },
  "permissions": {
    "query": true,
    "alerts": true,
    "admin": false
  },
  "query_limits": {
    "max_duration": "30s",
    "max_series": 1000
  },
  "fallback": {
    "enabled": false
  }
}

Available tools

prom_query

Execute an instant PromQL query for current values. Returns the metric, value, timestamp, and a brief summary.

prom_query_range

Execute a range query over time, returning a matrix of values with per-series metrics and aggregate stats.

prom_series

Find series that match given label selectors to identify relevant metrics.

prom_labels

Get label names or values for matching series to aid in query construction.

prom_alerts

Fetch current alert status and optional filtering by state or name.

prom_rules

Retrieve alerting or recording rules and their definitions.

prom_targets

Inspect scrape target health and last scrape statistics.

prom_metadata

Query metric metadata such as help text, type, and unit.

prom_analyze

AI-powered analysis to interpret metric behavior, summarize changes, and suggest queries.

prom_suggest_query

Provide natural-language driven PromQL query suggestions.