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
npx mdskills install yshngg/pmcp@yshngg? Sign in with GitHub to claim this listing.Comprehensive 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.