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
- Features
- Architecture
- Requirements
- Installation
- Usage
- API Compatibility
- Binding Blocks
- Contributing
- License
- 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:
- Go to PMCP Releases
- Download the appropriate binary for your platform from the Assets section
- 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
| 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
PMCP maintains 100% compatibility with the Prometheus HTTP API v1. Every tool and endpoint corresponds directly to the official Prometheus API:
Query & Data Retrieval
| PMCP 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
| PMCP 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
| PMCP 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
| PMCP Tool | Prometheus Endpoint | HTTP Method | Purpose |
|---|---|---|---|
| Config | /api/v1/status/config | GET | Get current configuration |
| Flags | /api/v1/status/flags | GET | Get runtime flags |
| Build Information | /api/v1/status/buildinfo | GET | Get build information |
| Runtime Information | /api/v1/status/runtimeinfo | GET | Get runtime information |
| TSDB Stats | /api/v1/status/tsdb | GET | Get TSDB statistics |
| WAL Replay Stats | /api/v1/status/walreplay | GET | Get WAL replay status |
TSDB Administration
| PMCP Tool | Prometheus Endpoint | HTTP Method | Purpose |
|---|---|---|---|
| TSDB Snapshot | /api/v1/admin/tsdb/snapshot | POST/PUT | Create TSDB snapshot |
| Delete Series | /api/v1/admin/tsdb/delete_series | POST/PUT | Delete time series data |
| Clean Tombstones | /api/v1/admin/tsdb/clean_tombstones | POST/PUT | Clean deleted data |
Management APIs
| PMCP Tool | Prometheus Endpoint | HTTP Method | Purpose |
|---|---|---|---|
| Health Check | /-/healthy | GET/HEAD | Check Prometheus health |
| Readiness Check | /-/ready | GET/HEAD | Check if ready to serve |
| Reload | /-/reload | PUT/POST | Reload configuration |
| Quit | /-/quit | PUT/POST | Graceful shutdown |
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
