# prometheus-mcp [Health: Active] **Category:** 📊 Monitoring **Repository:** https://github.com/mshegolev/prometheus-mcp **GitHub Stars:** 0 **Views:** 5 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/prometheus-mcp ## Description Prometheus MCP — query metrics, inspect alerts, and explore scrape targets (read-only). ## Tools Capabilities this server exposes over MCP: - **prometheus_list_metrics** — List all metric names known to Prometheus, with optional substring filter. Wraps ``GET /api/v1/label/__name__/values``. Prometheus returns all metric names at once — no pagination. Output is capped at 500 metrics after filtering, with a truncation hint when more exist. Use this first to discover valid metric names before writing PromQL expressions for ``prometheus_query`` or ``prometheus_query_range``. Examples: - Use when: "What metrics does Prometheus have about HTTP requests?" → ``pattern='http'``; read the ``metrics`` list. - Use when: "List all node_exporter metrics" → ``pattern='node_'``. - Use when: Starting a monitoring investigation — list metrics first to discover what's instrumented, then query specific ones. - Don't use when: You already know the exact metric name and want to query its value (call ``prometheus_query`` directly — one fewer round trip). - Don't use when: You want to see current alert state (call ``prometheus_list_alerts``). Returns: dict with ``total_count`` / ``returned_count`` / ``truncated`` / ``pattern`` / ``metrics`` (sorted list). - **prometheus_query** — Execute an instant PromQL query against Prometheus. Wraps ``GET /api/v1/query``. Returns the result type (vector, scalar, matrix, string) and a list of samples each carrying labels, timestamp, and value. For ``vector`` results each element is one time series at the evaluation instant. Examples: - Use when: "Is the payment service up right now?" → ``query='up{job="payment-service"}'``. - Use when: "What is the current HTTP request rate?" → ``query='sum(rate(http_requests_total[5m])) by (job)'``. - Use when: "Show me all metrics for a specific instance" → ``query='{instance="localhost:9090"}'``. - Don't use when: You want to see how a metric changed over time (call ``prometheus_query_range`` with start/end/step). - Don't use when: You don't know the metric name yet (call ``prometheus_list_metrics`` first to discover names). Returns: dict with ``query`` / ``time`` / ``result_type`` / ``result_count`` / ``data`` (list of samples with ``labels``, ``timestamp``, ``value``). - **prometheus_query_range** — Execute a PromQL range query returning time-series data points. Wraps ``GET /api/v1/query_range``. Returns one series per matching time series, each with labels and a list of ``[timestamp, value]`` pairs. Total points across all series are capped at 5000 with a truncation hint. Prometheus may reject the query with HTTP 422 (bad_data) if the step produces too many data points (> 11,000 per series). Increase the step or narrow the time range if this happens. Note: The Prometheus API does not support filtering by branch or commit in this endpoint — filters are expressed purely in PromQL label matchers. Examples: - Use when: "Show me CPU usage over the last hour with 1-minute resolution" → ``query='rate(node_cpu_seconds_total[5m])'``, ``step='1m'``. - Use when: "Graph HTTP error rate for the last 24 hours" → ``query='rate(http_requests_total{status=~"5.."}[5m])'``, ``start='2024-01-15T00:00:00Z'``, ``end='2024-01-16T00:00:00Z'``, ``step='5m'``. - Use when: Investigating a past incident — pick the time window of the incident and use a fine step. - Don't use when: You only want the current value (call ``prometheus_query`` — faster and simpler). - Don't use when: You want alert history (call ``prometheus_list_alerts``). Returns: dict with ``query`` / ``start`` / ``end`` / ``step`` / ``result_type`` / ``series_count`` / ``total_points`` / ``truncated`` / ``data`` (list of series with ``labels``, ``point_count``, ``values``). - **prometheus_list_alerts** — List all active and pending alerts from Prometheus. Wraps ``GET /api/v1/alerts``. Returns every alert that Prometheus currently tracks, with labels (including ``alertname``, ``severity``), state (``firing`` / ``pending``), the time it became active, and its current value. Also returns a summary grouped by state and a count by severity label. Examples: - Use when: "Are there any firing alerts right now?" → check ``firing_count`` and ``alerts`` where ``state='firing'``. - Use when: "Show me all critical alerts" → filter ``alerts`` by ``labels.severity == 'critical'``. - Use when: Checking system health during an incident — list alerts first to understand what's firing before querying metrics. - Don't use when: You want historical alert data (Prometheus stores only current state; use Alertmanager or a recording rule for history). - Don't use when: You want raw metric values (call ``prometheus_query`` or ``prometheus_query_range``). Returns: dict with ``total_count`` / ``firing_count`` / ``pending_count`` / ``state_summary`` / ``alerts`` (list with ``labels``, ``annotations``, ``state``, ``active_at``, ``value``). Enhanced with correlation information when requested. - **prometheus_list_targets** — List Prometheus scrape targets, summarised by job and health. Wraps ``GET /api/v1/targets``. Returns scrape targets with job name, instance address, health status (``up`` / ``down`` / ``unknown``), last scrape duration in milliseconds, and any last error. Also returns a summary grouped by job and health state. Examples: - Use when: "Which targets are currently down?" → filter ``targets`` where ``health='down'`` and check ``last_error``. - Use when: "How many instances of the 'node-exporter' job are up?" → check ``job_summary`` for the 'node-exporter' entry. - Use when: Investigating a scrape failure — list targets for the affected job to see which instances have errors. - Don't use when: You want metric values from a target (call ``prometheus_query`` with label matchers instead). - Don't use when: You want alert status (call ``prometheus_list_alerts`` instead). Returns: dict with ``state_filter`` / ``total_count`` / ``up_count`` / ``down_count`` / ``unknown_count`` / ``job_summary`` (per-job health counts) / ``targets`` (list with ``job``, ``instance``, ``health``, ``last_scrape_duration_ms``, ``last_error``, ``labels``). - **prometheus_get_metric_metadata** — Get metric metadata (HELP text, TYPE, UNIT) from Prometheus. Wraps ``GET /api/v1/metadata``. Returns the metadata that Prometheus scraped from ``HELP``, ``TYPE``, and ``UNIT`` lines in the exposition format. Each metric may have multiple metadata entries if different scrape targets expose different help strings. Use this to understand what a metric measures, its type (counter, gauge, histogram, summary), and unit — essential for writing correct PromQL. For example, knowing a metric is a counter means you should use ``rate()`` or ``increase()``; a gauge can be used directly. Examples: - Use when: "What does http_requests_total measure?" → ``metric='http_requests_total'``; read ``help`` and ``type``. - Use when: "Show me all histogram metrics" → call with no filter; filter results where ``type='histogram'``. - Use when: Starting an investigation — check metric types before writing PromQL to avoid using rate() on a gauge. - Don't use when: You already know the metric type and want to query values (call ``prometheus_query`` directly). Returns: dict with ``metric`` / ``total_count`` / ``returned_count`` / ``truncated`` / ``metadata`` (dict of metric name → list of ``{type, help, unit}``). - **prometheus_list_label_values** — List all values for a specific label from Prometheus. Wraps ``GET /api/v1/label/{label_name}/values``. Returns all distinct values for the named label across all time series, optionally filtered by a series selector. Use this to discover what entities exist for a given label dimension — for example, which jobs are running, which instances are scraped, or which namespaces have metrics. This is essential for building targeted PromQL queries during investigation. Examples: - Use when: "What jobs does Prometheus scrape?" → ``label='job'``; read the ``values`` list. - Use when: "What instances are in the 'node-exporter' job?" → ``label='instance'``, ``match='{job="node-exporter"}'``. - Use when: "What namespaces have metrics?" → ``label='namespace'``. - Don't use when: You want metric names (call ``prometheus_list_metrics`` — has substring filtering). - Don't use when: You want current metric values (call ``prometheus_query`` with a PromQL expression). Returns: dict with ``label`` / ``match`` / ``total_count`` / ``returned_count`` / ``truncated`` / ``values`` (sorted list). - **prometheus_list_rules** — List recording and alerting rules from Prometheus. Wraps ``GET /api/v1/rules``. Returns rule groups with their rules, including the PromQL expression, rule type (recording or alerting), and for alerting rules their current state (firing/pending/inactive). Use this to understand the alerting configuration, find recording rules that pre-compute useful aggregations, and investigate which rules are currently firing or have health issues. Examples: - Use when: "What alerting rules are configured?" → ``type='alert'``; inspect rule names and expressions. - Use when: "Are there any recording rules I can use instead of computing aggregations from scratch?" → ``type='record'``; look for rules matching your investigation. - Use when: "Why is this alert firing? What's its PromQL expression?" → call with no filter; find the alert by name; read its ``query``. - Don't use when: You want to see which alerts are currently firing (call ``prometheus_list_alerts`` — shows active alerts with state and value, without the PromQL definition). Returns: dict with ``type_filter`` / ``total_groups`` / ``total_rules`` / ``recording_count`` / ``alerting_count`` / ``groups`` (list of rule groups with ``name``, ``file``, ``rule_count``, ``rules``). - **alertmanager_list_silences** — List all silences from Alertmanager. Wraps ``GET /api/v2/silences``. Returns silences with matchers, status (active/pending/expired), creator, comment, and time bounds. Use this to understand which alerts are currently silenced and why. During incident handoffs, knowing what's silenced is critical — a silenced alert is invisible in Prometheus ``/alerts``. Examples: - Use when: "Is the HighCPU alert silenced?" → search silences for matching matchers. - Use when: "Who silenced alerts for the payment service?" → check ``createdBy`` and ``comment``. - Don't use when: You want active firing alerts (call ``alertmanager_list_alerts``). Returns: dict with ``total_count`` / ``active_count`` / ``pending_count`` / ``expired_count`` / ``silences`` (list with matchers, status, etc.). - **alertmanager_list_alerts** — List alerts from Alertmanager with suppression state. Wraps ``GET /api/v2/alerts``. Returns alerts with their status (active/suppressed/unprocessed), silence IDs, and inhibition IDs. Unlike ``prometheus_list_alerts``, this shows WHY an alert is or isn't firing — suppressed alerts include ``silencedBy`` and ``inhibitedBy`` arrays. Examples: - Use when: "Why isn't the HighCPU alert firing?" → check if it's suppressed (silencedBy or inhibitedBy). - Use when: "Show all suppressed alerts" → filter by ``status.state == 'suppressed'``. - Don't use when: You want Prometheus-side alert state (call ``prometheus_list_alerts``). Returns: dict with ``total_count`` / ``active_count`` / ``suppressed_count`` / ``unprocessed_count`` / ``alerts`` (list with status, silencedBy, etc.). - **alertmanager_get_status** — Get Alertmanager cluster status, version, and config. Wraps ``GET /api/v2/status``. Returns cluster state (ready/settling), version info, uptime, and the raw configuration YAML. Examples: - Use when: "Is Alertmanager healthy?" → check ``cluster_status``. - Use when: "What version of Alertmanager is running?" → check ``version_info``. - Don't use when: You want to see active alerts (call ``alertmanager_list_alerts``). Returns: dict with ``cluster_status`` / ``version_info`` / ``uptime`` / ``config_yaml``. - **alertmanager_list_alert_groups** — List alert groups from Alertmanager showing routing topology. Wraps ``GET /api/v2/alerts/groups``. Returns groups with their labels, receiver, and alert count — shows how alerts are grouped for notification. Examples: - Use when: "Why did I get one notification instead of many?" → check which alerts are in the same group. - Use when: "What receiver handles payment alerts?" → find the group and check its receiver. - Don't use when: You want individual alert details (call ``alertmanager_list_alerts``). Returns: dict with ``total_groups`` / ``total_alerts`` / ``groups`` (list with ``labels``, ``receiver``, ``alert_count``). - **correlate_alerts_across_instances** — Correlate alerts across multiple Prometheus instances. Identifies related alerts that fire simultaneously or in sequence across different Prometheus instances using temporal windows and label similarity. Use this to: - Understand cross-instance incident scope - Identify related alerts in different clusters/regions - Detect systemic issues affecting multiple instances Examples: - "Are there related alerts firing across our US and EU clusters?" - "Show me alerts that might be related to this HighCPU alert" Returns: CorrelationResult with correlated alerts, groups, and cascades. - **group_alerts_by_service** — Group alerts by service identifiers across all instances. Clusters related alerts into service-level incident analysis bundles. Use this to: - Understand which services are affected by current incidents - Focus incident response efforts on specific service teams - Identify services with multiple simultaneous alerts Examples: - "Which services are currently experiencing alerts?" - "Group all alerts by service for my incident report" Returns: AlertGroupResult with alerts grouped by service identifier. - **detect_cascading_alerts** — Detect cascading alert patterns with directional dependency inference. Identifies alert propagation patterns that indicate dependency failures. Use this to: - Trace failure propagation paths through your system - Identify root cause candidates for complex incidents - Understand service dependency relationships Examples: - "What alerts typically fire after DatabaseConnectionFailed?" - "Show me the failure propagation chain in this incident" Returns: CascadeDetectionResult with detected cascades and root causes. - **prometheus_map_service_dependencies** — Map service-to-service dependencies from live Prometheus traffic metrics. Aggregates ``rate([])`` by (source_label, destination_label) via ``query_range`` and turns each returned series into a directed dependency edge (nodes = services, edge weight = mean request rate). No simulation — every node/edge comes from real series. When ``error_matcher`` is supplied a second query derives a per-edge error rate. Use this to: - Discover which services call which, and how heavily. - Spot high-error dependencies during an incident. Examples: - "Map dependencies for the prod namespace over the last 15 minutes" → ``matchers={"namespace": "prod"}``, ``time_window="15m"``. - "Which edges are erroring?" → ``error_matcher='response_code=~"5.."'``. Returns: ServiceDependencyMapResult with ``nodes`` and directed ``edges`` (sorted by throughput), plus the query parameters used. - **federation_list_instances** — List all configured Prometheus and Alertmanager instances with health status - **prometheus_health_check** — Check Prometheus liveness and readiness. Calls ``GET /-/healthy`` and ``GET /-/ready`` — management endpoints outside the ``/api/v1`` namespace. Returns whether each probe returned a 200 status code. Use this to verify Prometheus is actually running before investigating blank query results. A failed health check means Prometheus is down; a failed readiness check means it's starting up or shutting down. Examples: - Use when: "Why are all my queries returning empty results?" → check if Prometheus is healthy first. - Use when: Setting up a new MCP connection — verify the target is reachable and healthy. - Don't use when: You want metric values (call ``prometheus_query``). Returns: dict with ``healthy`` (bool), ``healthy_status_code``, ``ready`` (bool), ``ready_status_code``. - **prometheus_get_cardinality** — Get TSDB statistics and cardinality data from Prometheus. Wraps ``GET /api/v1/status/tsdb``. Returns head stats (total series, chunks, time range) and top-N lists: metrics by series count, labels by value count, and labels by memory usage. Use this to investigate cardinality explosions — the #1 operational Prometheus problem. High series counts slow queries and increase memory. Examples: - Use when: "Why is Prometheus using so much memory?" → check ``num_series`` and ``top_metrics_by_series``. - Use when: "Which labels have the most values?" → check ``top_labels_by_value_count``. - Don't use when: You want current metric values (call ``prometheus_query``). Returns: dict with ``num_series`` / ``chunk_count`` / ``min_time`` / ``max_time`` / ``top_metrics_by_series`` / ``top_labels_by_value_count`` / ``top_labels_by_memory_bytes``. - **prometheus_get_runtime_info** — Get Prometheus runtime information. Wraps ``GET /api/v1/status/runtimeinfo``. Returns operational data: goroutine count, time series count, storage retention policy, start time, corruption count, and config reload status. Examples: - Use when: "Why is Prometheus slow?" → check goroutine count and time series count. - Use when: "What's the retention policy?" → check ``storage_retention``. - Don't use when: You want the Prometheus version (call ``prometheus_get_build_info``). Returns: dict with ``start_time`` / ``goroutine_count`` / ``time_series_count`` / ``storage_retention`` / ``corruptionCount`` / ``reloadConfigSuccess`` / ``lastConfigTime``. - **prometheus_get_build_info** — Get Prometheus build information. Wraps ``GET /api/v1/status/buildinfo``. Returns version, Go version, Git revision, branch, build user, and build date. Examples: - Use when: "What version of Prometheus is running?" → check ``version``. - Use when: Debugging version-specific behavior. - Don't use when: You want runtime stats (call ``prometheus_get_runtime_info``). Returns: dict with ``version`` / ``revision`` / ``branch`` / ``buildUser`` / ``buildDate`` / ``goVersion``. ## Claude Desktop Quick Installation Install path detected from listing signals. Uses `uvx` (confidence: high): ```json "mcpServers": { "prometheus-mcp": { "command": "uvx", "args": ["prometheus-mcp"], "env": { "PROMETHEUS_URL": "", "PROMETHEUS_TOKEN": "", "PROMETHEUS_USERNAME": "", "PROMETHEUS_PASSWORD": "", "PROMETHEUS_SSL_VERIFY": "" } } } ``` **Requires environment variables:** `PROMETHEUS_URL`, `PROMETHEUS_TOKEN`, `PROMETHEUS_USERNAME`, `PROMETHEUS_PASSWORD`, `PROMETHEUS_SSL_VERIFY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for). ## Documentation ## What prometheus-mcp does The prometheus-mcp MCP server exposes selected Prometheus read operations to an MCP client. Agents can discover available metric names, run PromQL expressions, review alerts, and inspect scrape targets without using Prometheus's web interface or manually constructing API requests. The server is read-only. Its five tools map to Prometheus HTTP API endpoints and do not modify metrics, rules, alerts, or target configuration. Results include structured data for programmatic handling and Markdown output for conversational display. ## How it works The server communicates with Prometheus over HTTP using one persistent Python `requests.Session`, which enables connection pooling. Requests have a 30-second timeout, and the session does not use environment proxy settings. Prometheus responses are converted into MCP tool results. `prometheus_list_metrics` retrieves metric names and can apply a case-insensitive substring filter. Results are limited to 500 names. `prometheus_query` runs an instant PromQL expression, optionally at a supplied RFC3339 or Unix timestamp. `prometheus_query_range` evaluates PromQL over a start and end time with a required step and returns timestamped series data. The alert tool reports active and pending alerts, including labels, state, activation time, and current value. The target tool reports scrape jobs and instance addresses with health, scrape duration, and error details. Targets can be filtered to active, dropped, or any state. ## Setup and configuration Install the prometheus-mcp MCP server from PyPI with `pip install prometheus-mcp`, or run it without installation using `uvx prometheus-mcp`. A Docker image can also be started with `PROMETHEUS_URL` supplied as an environment variable. `PROMETHEUS_URL` is required and should identify the Prometheus server without a trailing slash. Authentication is optional: set `PROMETHEUS_TOKEN` for Bearer authentication, or provide `PROMETHEUS_USERNAME` and `PROMETHEUS_PASSWORD` for HTTP Basic authentication. A token takes precedence when both authentication methods are configured. Set `PROMETHEUS_SSL_VERIFY=false` when connecting to a server that uses a self-signed certificate. For Claude Desktop or Claude Code, add a stdio entry that runs either the installed `prometheus-mcp` command or `uvx` with `prometheus-mcp` as its argument, then place the environment variables in that MCP configuration. ## Tools and capabilities The prometheus-mcp MCP server provides: - Metric-name discovery with an optional substring filter. - Instant PromQL evaluation with current or specified-time results. - Range PromQL evaluation with configurable resolution. - Active and pending alert inspection with state counts. - Scrape-target inspection with health, job, duration, and error information. Range-query output is capped at 5,000 data points across all returned series. Prometheus may reject a query that would exceed 11,000 points per series; increasing the step or narrowing the time window addresses that condition. ## Limitations and notes The tools do not support writes, so they cannot alter Prometheus data or configuration. Range queries use PromQL label matchers for filtering; the range API does not provide branch or commit filters. Metric discovery is capped at 500 results after filtering, and long time windows may require a larger step. The server expects Prometheus to be reachable at the configured URL and does not route requests through environment proxies. _Full upstream README: https://allmcps.com/mcp/prometheus-mcp/readme_