pmcp

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.

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

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

🚀 A Prometheus Model Context Protocol Server.

Related MCP Servers

mcp-server-prometheus
loglmhq
-
security
A
license
-
quality
MCP server for interacting with Prometheus metrics and data.
Last updated -
16
MIT License
MCP Server Fetch TypeScript
tatn
A
security
A
license
A
quality
A Model Context Protocol server that provides web content fetching and conversion capabilities.
Last updated -
4
357
2
MIT License
Medusa MCP Server
SGFGOV
A
security
A
license
A
quality
A Model Context Protocol server that provides a scalable backend solution for efficient interaction with Medusa's data models through the JavaScript SDK.
Last updated -
48
40
MIT License
Prometheus MCP Server
moohoorama
-
security
F
license
-
quality
A tool that enables access to Prometheus metrics data through a Model Context Protocol server, allowing interaction with monitoring data using natural language.
Last updated -

View all related MCP servers