pmcp

Prometheus Model Context Protocol Server

A Golang-based Model Context Protocol (MCP) server implementation for Prometheus that enables natural language interactions with Prometheus metrics and queries.

Built with Go, prometheus-mcp-server provides a robust, type-safe interface that maintains full consistency with the Prometheus HTTP API, allowing you to query and manage your Prometheus instance through natural language conversations with MCP-compatible clients.

---

Table of Contents

1. Features
2. Architecture
3. Requirements
4. Installation
5. Usage
- Command Line Flags
6. API Compatibility
7. Binding Blocks
- Tools
- Prompts
8. Contributing
9. License
10. Acknowledgments

---

Features

- 🔥 Golang Implementation: Built with Go 1.23+ for performance, reliability, and type safety
- 📊 Complete Prometheus API Coverage: Full compatibility with Prometheus HTTP API v1
- ⚡ Instant Query: Execute Prometheus queries at a specific point in time
- 📈 Range Query: Retrieve historical metric data over defined time ranges
- 🔍 Metadata Query: Discover time series, label names, and label values
- 🎯 Target & Rule Management: Monitor targets, rules, and alerting configurations
- 🛠️ TSDB Administration: Advanced database operations including snapshots and series deletion
- 🌐 Multiple Transport Options: Support for HTTP, Server-Sent Events (SSE), and stdio
- 🤖 MCP Integration: Seamless communication with MCP-compatible clients like Claude Desktop

---

Architecture

prometheus-mcp-server is designed as a Golang microservice that acts as a bridge between MCP clients and Prometheus servers. It provides:

- Type-safe API bindings using Go structs that mirror Prometheus API responses
- Modular package structure for maintainability and extensibility
- Comprehensive error handling with proper Go error propagation
- Clean separation of concerns between transport, API client, and business logic

---

Requirements

- Go 1.23.0 or higher
- A running Prometheus server (v2.x)
- Compatible MCP client (Claude Desktop, custom implementations, etc.)

---

Installation

Using Docker (Recommended)

Pull the pre-built image from GitHub Container Registry:

# Pull the latest image
docker pull ghcr.io/yshngg/prometheus-mcp-server:latest
Run with stdio transport (for desktop clients)
docker run --rm ghcr.io/yshngg/prometheus-mcp-server:latest --prom-addr="http://host.docker.internal:9090"
Run with HTTP transport
docker run --rm -p 8080:8080 ghcr.io/yshngg/prometheus-mcp-server:latest --prom-addr="http://host.docker.internal:9090" --transport=http --mcp-addr="0.0.0.0:8080"

Alternatively, build locally:

docker build -t prometheus-mcp-server .
docker run -p 8080:8080 prometheus-mcp-server --prom-addr="http://prometheus:9090" --transport=http

Download Pre-built Binary

Download the latest release from GitHub:

1. Go to prometheus-mcp-server Releases
2. Download the appropriate binary for your platform from the Assets section
3. Extract and run:

# Linux/macOS example
tar -xzf prometheus-mcp-server-<version>.linux-amd64.tar.gz
./prometheus-mcp-server --prom-addr="http://localhost:9090"
Windows example
unzip prometheus-mcp-server-<version>.windows-amd64.zip
prometheus-mcp-server.exe --prom-addr="http://localhost:9090"

Building from Source

git clone https://github.com/yshngg/prometheus-mcp-server.git
cd prometheus-mcp-server
make build
Binary will be available as ./prometheus-mcp-server

Using Go Install

Install the prometheus-mcp-server binary directly from source:

go install github.com/yshngg/prometheus-mcp-server@latest

Ensure $GOPATH/bin is in your $PATH.

---

Usage

Run the server by specifying your Prometheus address and preferred transport:

# Default (stdio transport) - ideal for desktop clients
prometheus-mcp-server --prom-addr="http://localhost:9090"
HTTP transport - for web-based integrations
prometheus-mcp-server --prom-addr="http://localhost:9090" --transport=http --mcp-addr="localhost:8080"
SSE transport - for real-time streaming (deprecated, use HTTP)
prometheus-mcp-server --prom-addr="http://localhost:9090" --transport=sse --mcp-addr="localhost:8080"

Command Line Flags

| Flag | Description | Default |
| ------------ | ------------------------------------------------- | ----------------------- |
| -help | Show help information. | N/A |
| -mcp-addr | Address for the MCP server to listen on. | localhost:8080 |
| -prom-addr | Prometheus server URL. | http://localhost:9090 |
| -transport | Communication transport (stdio, http, sse). | stdio |
| -version | Print version and exit. | N/A |

---

API Compatibility

prometheus-mcp-server maintains 100% compatibility with the Prometheus HTTP API v1. Every tool and endpoint corresponds directly to the official Prometheus API:

Query & Data Retrieval

| Tool | Prometheus Endpoint | HTTP Method | Purpose |
| ------------- | --------------------- | ----------- | ----------------------- |
| Instant Query | /api/v1/query | GET/POST | Execute instant queries |
| Range Query | /api/v1/query_range | GET/POST | Execute range queries |

Metadata & Discovery

| Tool | Prometheus Endpoint | HTTP Method | Purpose |
| --------------------- | ---------------------------- | ----------- | -------------------------------- |
| Find Series by Labels | /api/v1/series | GET/POST | Find matching time series |
| List Label Names | /api/v1/labels | GET/POST | List all label names |
| List Label Values | /api/v1/label/:name/values | GET | List values for a specific label |
| Target Discovery | /api/v1/targets | GET | Get target information |
| Target Metadata Query | /api/v1/targets/metadata | GET | Get metadata from targets |
| Metric Metadata Query | /api/v1/metadata | GET | Get metric metadata |

Rules & Alerts

| Tool | Prometheus Endpoint | HTTP Method | Purpose |
| ---------------------- | ----------------------- | ----------- | ---------------------------- |
| Alert Query | /api/v1/alerts | GET | Get all active alerts |
| Rule Query | /api/v1/rules | GET | Get recording/alerting rules |
| Alertmanager Discovery | /api/v1/alertmanagers | GET | Get alertmanager information |

Status & Configuration

…