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
Add this skill
npx mdskills install yshngg/pmcpComprehensive MCP server providing complete Prometheus API access with excellent documentation
1# Prometheus Model Context Protocol Server23[](https://codecov.io/gh/yshngg/prometheus-mcp-server)4[](https://goreportcard.com/report/github.com/yshngg/prometheus-mcp-server)56**A Golang-based Model Context Protocol (MCP) server implementation for Prometheus that enables natural language interactions with Prometheus metrics and queries.**78**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.910---1112## Table of Contents13141. [Features](#features)152. [Architecture](#architecture)163. [Requirements](#requirements)174. [Installation](#installation)185. [Usage](#usage)19 - [Command Line Flags](#command-line-flags)206. [API Compatibility](#api-compatibility)217. [Binding Blocks](#binding-blocks)22 - [Tools](#tools)23 - [Prompts](#prompts)248. [Contributing](#contributing)259. [License](#license)2610. [Acknowledgments](#acknowledgments)2728---2930## Features3132- **🔥 Golang Implementation**: Built with Go 1.23+ for performance, reliability, and type safety33- **📊 Complete Prometheus API Coverage**: Full compatibility with Prometheus HTTP API v134- **⚡ Instant Query**: Execute Prometheus queries at a specific point in time35- **📈 Range Query**: Retrieve historical metric data over defined time ranges36- **🔍 Metadata Query**: Discover time series, label names, and label values37- **🎯 Target & Rule Management**: Monitor targets, rules, and alerting configurations38- **🛠️ TSDB Administration**: Advanced database operations including snapshots and series deletion39- **🌐 Multiple Transport Options**: Support for HTTP, Server-Sent Events (SSE), and stdio40- **🤖 MCP Integration**: Seamless communication with MCP-compatible clients like Claude Desktop4142---4344## Architecture4546`prometheus-mcp-server` is designed as a **Golang microservice** that acts as a bridge between MCP clients and Prometheus servers. It provides:4748- **Type-safe API bindings** using Go structs that mirror Prometheus API responses49- **Modular package structure** for maintainability and extensibility50- **Comprehensive error handling** with proper Go error propagation51- **Clean separation of concerns** between transport, API client, and business logic5253---5455## Requirements5657- **Go 1.23.0** or higher58- A running **Prometheus server** (v2.x)59- Compatible MCP client (Claude Desktop, custom implementations, etc.)6061---6263## Installation6465### Using Docker (Recommended)6667Pull the pre-built image from GitHub Container Registry:6869```bash70# Pull the latest image71docker pull ghcr.io/yshngg/prometheus-mcp-server:latest7273# Run with stdio transport (for desktop clients)74docker run --rm ghcr.io/yshngg/prometheus-mcp-server:latest --prom-addr="http://host.docker.internal:9090"7576# Run with HTTP transport77docker 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"78```7980Alternatively, build locally:8182```bash83docker build -t prometheus-mcp-server .84docker run -p 8080:8080 prometheus-mcp-server --prom-addr="http://prometheus:9090" --transport=http85```8687### Download Pre-built Binary8889Download the latest release from GitHub:90911. Go to `prometheus-mcp-server` [Releases](https://github.com/yshngg/prometheus-mcp-server/releases)922. Download the appropriate binary for your platform from the **Assets** section933. Extract and run:9495```bash96# Linux/macOS example97tar -xzf prometheus-mcp-server-<version>.linux-amd64.tar.gz98./prometheus-mcp-server --prom-addr="http://localhost:9090"99100# Windows example101unzip prometheus-mcp-server-<version>.windows-amd64.zip102prometheus-mcp-server.exe --prom-addr="http://localhost:9090"103```104105### Building from Source106107```bash108git clone https://github.com/yshngg/prometheus-mcp-server.git109cd prometheus-mcp-server110make build111# Binary will be available as ./prometheus-mcp-server112```113114### Using Go Install115116Install the `prometheus-mcp-server` binary directly from source:117118```bash119go install github.com/yshngg/prometheus-mcp-server@latest120```121122Ensure `$GOPATH/bin` is in your `$PATH`.123124---125126## Usage127128Run the server by specifying your Prometheus address and preferred transport:129130```bash131# Default (stdio transport) - ideal for desktop clients132prometheus-mcp-server --prom-addr="http://localhost:9090"133134# HTTP transport - for web-based integrations135prometheus-mcp-server --prom-addr="http://localhost:9090" --transport=http --mcp-addr="localhost:8080"136137# SSE transport - for real-time streaming (deprecated, use HTTP)138prometheus-mcp-server --prom-addr="http://localhost:9090" --transport=sse --mcp-addr="localhost:8080"139```140141### Command Line Flags142143| Flag | Description | Default |144| ------------ | ------------------------------------------------- | ----------------------- |145| `-help` | Show help information. | N/A |146| `-mcp-addr` | Address for the MCP server to listen on. | `localhost:8080` |147| `-prom-addr` | Prometheus server URL. | `http://localhost:9090` |148| `-transport` | Communication transport (`stdio`, `http`, `sse`). | `stdio` |149| `-version` | Print version and exit. | N/A |150151---152153## API Compatibility154155`prometheus-mcp-server` maintains **100% compatibility** with the Prometheus HTTP API v1. Every tool and endpoint corresponds directly to the official Prometheus API:156157### Query & Data Retrieval158159| Tool | Prometheus Endpoint | HTTP Method | Purpose |160| ------------- | --------------------- | ----------- | ----------------------- |161| Instant Query | `/api/v1/query` | GET/POST | Execute instant queries |162| Range Query | `/api/v1/query_range` | GET/POST | Execute range queries |163164### Metadata & Discovery165166| Tool | Prometheus Endpoint | HTTP Method | Purpose |167| --------------------- | ---------------------------- | ----------- | -------------------------------- |168| Find Series by Labels | `/api/v1/series` | GET/POST | Find matching time series |169| List Label Names | `/api/v1/labels` | GET/POST | List all label names |170| List Label Values | `/api/v1/label/:name/values` | GET | List values for a specific label |171| Target Discovery | `/api/v1/targets` | GET | Get target information |172| Target Metadata Query | `/api/v1/targets/metadata` | GET | Get metadata from targets |173| Metric Metadata Query | `/api/v1/metadata` | GET | Get metric metadata |174175### Rules & Alerts176177| Tool | Prometheus Endpoint | HTTP Method | Purpose |178| ---------------------- | ----------------------- | ----------- | ---------------------------- |179| Alert Query | `/api/v1/alerts` | GET | Get all active alerts |180| Rule Query | `/api/v1/rules` | GET | Get recording/alerting rules |181| Alertmanager Discovery | `/api/v1/alertmanagers` | GET | Get alertmanager information |182183### Status & Configuration184185| Tool | Prometheus Endpoint | HTTP Method | Purpose |186| ------------------- | ---------------------------- | ----------- | ------------------------- |187| Config | `/api/v1/status/config` | GET | Get current configuration |188| Flags | `/api/v1/status/flags` | GET | Get runtime flags |189| Build Information | `/api/v1/status/buildinfo` | GET | Get build information |190| Runtime Information | `/api/v1/status/runtimeinfo` | GET | Get runtime information |191| TSDB Stats | `/api/v1/status/tsdb` | GET | Get TSDB statistics |192| WAL Replay Stats | `/api/v1/status/walreplay` | GET | Get WAL replay status |193194### TSDB Administration195196| Tool | Prometheus Endpoint | HTTP Method | Purpose |197| ---------------- | ------------------------------------- | ----------- | ----------------------- |198| TSDB Snapshot | `/api/v1/admin/tsdb/snapshot` | POST/PUT | Create TSDB snapshot |199| Delete Series | `/api/v1/admin/tsdb/delete_series` | POST/PUT | Delete time series data |200| Clean Tombstones | `/api/v1/admin/tsdb/clean_tombstones` | POST/PUT | Clean deleted data |201202### Management APIs203204| Tool | Prometheus Endpoint | HTTP Method | Purpose |205| --------------- | ------------------- | ----------- | ----------------------- |206| Health Check | `/-/healthy` | GET/HEAD | Check Prometheus health |207| Readiness Check | `/-/ready` | GET/HEAD | Check if ready to serve |208| Reload | `/-/reload` | PUT/POST | Reload configuration |209| Quit | `/-/quit` | PUT/POST | Graceful shutdown |210211**All query parameters, response formats, and error codes match the official Prometheus API specification.**212213---214215## Binding Blocks216217### Tools218219**Expression Queries** (Core Prometheus functionality):220221- **Instant Query**: Evaluate an instant query at a single point in time222- **Range Query**: Evaluate an expression query over a range of time223224**Metadata Queries** (Series and label discovery):225226- **Find Series by Labels**: Return the list of time series that match a certain label set227- **List Label Names**: Return a list of label names228- **List Label Values**: Return a list of label values for a provided label name229- **Target Metadata Query**: Return metadata about metrics currently scraped from targets230- **Metric Metadata Query**: Return metadata about metrics currently scraped from targets (without target information)231232**Discovery & Monitoring**:233234- **Target Discovery**: Return an overview of the current state of the Prometheus target discovery235- **Alert Query**: Return a list of all active alerts236- **Rule Query**: Return a list of alerting and recording rules that are currently loaded237- **Alertmanager Discovery**: Return an overview of the current state of the Prometheus alertmanager discovery238239**Status & Configuration**:240241- **Config**: Return currently loaded configuration file242- **Flags**: Return flag values that Prometheus was configured with243- **Runtime Information**: Return various runtime information properties about the Prometheus server244- **Build Information**: Return various build information properties about the Prometheus server245- **TSDB Stats**: Return various cardinality statistics about the Prometheus TSDB246- **WAL Replay Stats**: Return information about the WAL replay247248**TSDB Admin APIs** (Advanced operations):249250- **TSDB Snapshot**: Create a snapshot of all current data into snapshots/`<datetime>`-`<rand>`251- **Delete Series**: Delete data for a selection of series in a time range252- **Clean Tombstones**: Remove the deleted data from disk and cleans up the existing tombstones253254**Management APIs**:255256- **Health Check**: Check Prometheus health257- **Readiness Check**: Check if Prometheus is ready to serve traffic (i.e. respond to queries)258- **Reload**: Trigger a reload of the Prometheus configuration and rule files259- **Quit**: Trigger a graceful shutdown of Prometheus260261### Prompts262263- **All Available Metrics**: Return a list of every metric exposed by the Prometheus instance264265---266267## Contributing268269Contributions are welcome! This is a **Golang project**, so please ensure:270271- Follow Go best practices and conventions272- Add appropriate tests for new functionality273- Maintain API compatibility with Prometheus274- Update documentation as needed275276Please submit a pull request or open an issue to discuss improvements.277278### Development Setup279280```bash281git clone https://github.com/yshngg/prometheus-mcp-server.git282cd prometheus-mcp-server283go mod download284make build285```286287---288289## License290291This project is licensed under the Apache License 2.0. See the [LICENSE](LICENSE) file for details.292293---294295## Acknowledgments296297- **Built with Go** using the official [Prometheus Go client library](https://github.com/prometheus/client_golang)298- Powered by [Model Context Protocol Go SDK](https://github.com/modelcontextprotocol/go-sdk)299- Inspired by [Prometheus](https://prometheus.io/) - the de facto standard for monitoring and alerting300
Full transparency — inspect the skill content before installing.