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, PMCP 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

PMCP 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/pmcp:latest

# Run with stdio transport (for desktop clients)
docker run --rm ghcr.io/yshngg/pmcp:latest --prom-addr="http://host.docker.internal:9090"

# Run with HTTP transport
docker run --rm -p 8080:8080 ghcr.io/yshngg/pmcp:latest --prom-addr="http://host.docker.internal:9090" --transport=http --mcp-addr="0.0.0.0:8080"

Alternatively, build locally:

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

Download Pre-built Binary

Download the latest release from GitHub:

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

# Linux/macOS example
tar -xzf pmcp-<version>.linux-amd64.tar.gz
./pmcp --prom-addr="http://localhost:9090"

# Windows example
unzip pmcp-<version>.windows-amd64.zip
pmcp.exe --prom-addr="http://localhost:9090"

Building from Source

git clone https://github.com/yshngg/pmcp.git
cd pmcp
make build
# Binary will be available as ./pmcp

Using Go Install

Install the pmcp binary directly from source:

go install github.com/yshngg/pmcp@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
pmcp --prom-addr="http://localhost:9090"

# HTTP transport - for web-based integrations
pmcp --prom-addr="http://localhost:9090" --transport=http --mcp-addr="localhost:8080"

# SSE transport - for real-time streaming (deprecated, use HTTP)
pmcp --prom-addr="http://localhost:9090" --transport=sse --mcp-addr="localhost:8080"

Command Line Flags

API Compatibility

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

Query & Data Retrieval

Metadata & Discovery

Rules & Alerts

Status & Configuration

TSDB Administration

Management APIs

All query parameters, response formats, and error codes match the official Prometheus API specification.

Binding Blocks

Tools

Expression Queries (Core Prometheus functionality):

• Instant Query: Evaluate an instant query at a single point in time
• Range Query: Evaluate an expression query over a range of time

Metadata Queries (Series and label discovery):

• Find Series by Labels: Return the list of time series that match a certain label set
• List Label Names: Return a list of label names
• List Label Values: Return a list of label values for a provided label name
• Target Metadata Query: Return metadata about metrics currently scraped from targets
• Metric Metadata Query: Return metadata about metrics currently scraped from targets (without target information)

Discovery & Monitoring:

• Target Discovery: Return an overview of the current state of the Prometheus target discovery
• Alert Query: Return a list of all active alerts
• Rule Query: Return a list of alerting and recording rules that are currently loaded
• Alertmanager Discovery: Return an overview of the current state of the Prometheus alertmanager discovery

Status & Configuration:

• Config: Return currently loaded configuration file
• Flags: Return flag values that Prometheus was configured with
• Runtime Information: Return various runtime information properties about the Prometheus server
• Build Information: Return various build information properties about the Prometheus server
• TSDB Stats: Return various cardinality statistics about the Prometheus TSDB
• WAL Replay Stats: Return information about the WAL replay

TSDB Admin APIs (Advanced operations):

• TSDB Snapshot: Create a snapshot of all current data into snapshots/<datetime>-<rand>
• Delete Series: Delete data for a selection of series in a time range
• Clean Tombstones: Remove the deleted data from disk and cleans up the existing tombstones

Management APIs:

• Health Check: Check Prometheus health
• Readiness Check: Check if Prometheus is ready to serve traffic (i.e. respond to queries)
• Reload: Trigger a reload of the Prometheus configuration and rule files
• Quit: Trigger a graceful shutdown of Prometheus

Prompts

• All Available Metrics: Return a list of every metric exposed by the Prometheus instance

Contributing

Contributions are welcome! This is a Golang project, so please ensure:

• Follow Go best practices and conventions
• Add appropriate tests for new functionality
• Maintain API compatibility with Prometheus
• Update documentation as needed

Please submit a pull request or open an issue to discuss improvements.

Development Setup

git clone https://github.com/yshngg/pmcp.git
cd pmcp
go mod download
make build

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

Acknowledgments

• Built with Go using the official Prometheus Go client library
• Powered by Model Context Protocol Go SDK
• Inspired by Prometheus - the de facto standard for monitoring and alerting