mcp-prometheus

vilosource/mcp-prometheus

3.2

If you are the rightful owner of mcp-prometheus and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

A Prometheus MCP server is designed to facilitate the integration and management of Prometheus monitoring systems using the Model Context Protocol (MCP).

MCP Prometheus Server

Model Context Protocol (MCP) server for Prometheus monitoring system. This server enables AI language models to query metrics, analyze time series data, and retrieve metadata from Prometheus.

Documentation

  • 📖 - How to use the MCP server with Claude Code
  • 🛠️ - Architecture and contribution guidelines
  • 📚 - Detailed tool specifications and response formats

Features

  • Instant Queries: Execute PromQL queries at a single point in time
  • Range Queries: Query metrics over time ranges for trend analysis
  • Metadata Discovery: Explore available metrics, labels, and targets
  • Series Exploration: Find time series matching label selectors
  • Target Information: View scrape target health and configuration
  • Caching: Built-in caching for frequently accessed metadata

Installation

Using pip

pip install -e .

Using Docker

docker build -t mcp-prometheus .
docker run -p 8000:8000 --env-file .env mcp-prometheus

Configuration

Create a .env file based on .env.example:

# Required
PROMETHEUS_URL=http://localhost:9090

# Optional authentication
PROMETHEUS_USERNAME=admin
PROMETHEUS_PASSWORD=password

# Optional settings
PROMETHEUS_TIMEOUT=30
PROMETHEUS_VERIFY_SSL=true

Usage

Command Line

# Run with stdio transport (default)
mcp-prometheus

# Run with SSE transport
mcp-prometheus --transport sse --port 8000

# With custom Prometheus URL
mcp-prometheus --prometheus-url http://prometheus.example.com:9090

# With authentication
mcp-prometheus --prometheus-username admin --prometheus-password secret

Available Tools

  1. query: Execute instant queries

    query(query="up", time="2024-01-01T00:00:00Z")

  2. query_range: Execute range queries

    query_range(query="rate(http_requests_total[5m])", start="1h", end="now", step="1m")

  3. series: Find series by label selectors

    series(match=["up", "http_requests_total{job=\"api\"}"])

  4. labels: Get all label names

    labels()

  5. label_values: Get values for a specific label

    label_values(label_name="job")

  6. targets: Get scrape target information

    targets()

  7. metadata: Get metric metadata

    metadata(metric="http_requests_total", limit=10)

Example Queries

Basic Metrics

  • up - Target up status
  • process_cpu_seconds_total - CPU usage
  • node_memory_MemAvailable_bytes - Available memory

Rate Calculations

  • rate(http_requests_total[5m]) - Request rate over 5 minutes
  • irate(cpu_usage_seconds_total[1m]) - Instant CPU rate

Aggregations

  • sum by (job) (up) - Count up targets by job
  • avg(node_load1) - Average 1-minute load

Development

Running Tests

pytest tests/

Code Style

# Format code
black src/

# Lint
ruff check src/

License

Same as the parent project.