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

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

Related MCP server: MCP Server Fetch TypeScript

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

prometheus-mcp-server 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/prometheus-mcp-server:latest

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

# Run with HTTP transport
docker 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"

Alternatively, build locally:

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

Download Pre-built Binary

Download the latest release from GitHub:

1. Go to prometheus-mcp-server Releases

2. Download the appropriate binary for your platform from the Assets section

3. Extract and run:

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

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

Building from Source

git clone https://github.com/yshngg/prometheus-mcp-server.git
cd prometheus-mcp-server
make build
# Binary will be available as ./prometheus-mcp-server

Using Go Install

Install the prometheus-mcp-server binary directly from source:

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

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

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

Command Line Flags

API Compatibility

prometheus-mcp-server 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/prometheus-mcp-server.git
cd prometheus-mcp-server
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