A Model Context Protocol (MCP) server that enables AI assistants to query and analyze Prometheus metrics through standardized interfaces.
What is prometheus-mcp-server
Prometheus MCP Server
A Model Context Protocol (MCP) server for Prometheus.
This provides access to your Prometheus metrics and queries through standardized MCP interfaces, allowing AI assistants to execute PromQL queries and analyze your metrics data.
Features
-
Execute PromQL queries against Prometheus
-
Discover and explore metrics
- List available metrics
- Get metadata for specific metrics
- View instant query results
- View range query results with different step intervals
-
Authentication support
- Basic auth from environment variables
- Bearer token auth from environment variables
-
Docker containerization support
-
Provide interactive tools for AI assistants
The list of tools is configurable, so you can choose which tools you want to make available to the MCP client. This is useful if you don't use certain functionality or if you don't want to take up too much of the context window.
Usage
-
Ensure your Prometheus server is accessible from the environment where you'll run this MCP server.
-
Configure the environment variables for your Prometheus server, either through a
.env
file or system environment variables:
# Required: Prometheus configuration
PROMETHEUS_URL=http://your-prometheus-server:9090
# Optional: Authentication credentials (if needed)
# Choose one of the following authentication methods if required:
# For basic auth
PROMETHEUS_USERNAME=your_username
PROMETHEUS_PASSWORD=your_password
# For bearer token auth
PROMETHEUS_TOKEN=your_token
# Optional: For multi-tenant setups like Cortex, Mimir or Thanos
ORG_ID=your_organization_id
- Add the server configuration to your client configuration file. For example, for Claude Desktop:
{
"mcpServers": {
"prometheus": {
"command": "uv",
"args": [
"--directory",
"<full path to prometheus-mcp-server directory>",
"run",
"src/prometheus_mcp_server/main.py"
],
"env": {
"PROMETHEUS_URL": "http://your-prometheus-server:9090",
"PROMETHEUS_USERNAME": "your_username",
"PROMETHEUS_PASSWORD": "your_password"
}
}
}
}
Note: if you see
Error: spawn uv ENOENT
in Claude Desktop, you may need to specify the full path touv
or set the environment variableNO_UV=1
in the configuration.
Docker Usage
This project includes Docker support for easy deployment and isolation.
Pre-built Docker Image
The easiest way to use this project is with the pre-built image from GitHub Container Registry:
docker pull ghcr.io/pab1it0/prometheus-mcp-server:latest
You can also use specific versions with tags:
docker pull ghcr.io/pab1it0/prometheus-mcp-server:1.0.0
Building the Docker Image Locally
If you prefer to build the image yourself:
docker build -t prometheus-mcp-server .
Running with Docker
You can run the server using Docker in several ways:
Using docker run with the pre-built image:
docker run -it --rm \
-e PROMETHEUS_URL=http://your-prometheus-server:9090 \
-e PROMETHEUS_USERNAME=your_username \
-e PROMETHEUS_PASSWORD=your_password \
ghcr.io/pab1it0/prometheus-mcp-server:latest
Using docker run with a locally built image:
docker run -it --rm \
-e PROMETHEUS_URL=http://your-prometheus-server:9090 \
-e PROMETHEUS_USERNAME=your_username \
-e PROMETHEUS_PASSWORD=your_password \
prometheus-mcp-server
Using docker-compose:
Create a .env
file with your Prometheus credentials and then run:
docker-compose up
Running with Docker in Claude Desktop
To use the containerized server with Claude Desktop, update the configuration to use Docker with the environment variables:
{
"mcpServers": {
"prometheus": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e", "PROMETHEUS_URL",
"-e", "PROMETHEUS_USERNAME",
"-e", "PROMETHEUS_PASSWORD",
"ghcr.io/pab1it0/prometheus-mcp-server:latest"
],
"env": {
"PROMETHEUS_URL": "http://your-prometheus-server:9090",
"PROMETHEUS_USERNAME": "your_username",
"PROMETHEUS_PASSWORD": "your_password"
}
}
}
}
This configuration passes the environment variables from Claude Desktop to the Docker container by using the -e
flag with just the variable name, and providing the actual values in the env
object.
Note about Docker implementation: The Docker setup has been updated to match the structure of the chess-mcp project, which has been proven to work correctly with Claude. The new implementation uses a multi-stage build process and runs the entry point script directly without an intermediary shell script. This approach ensures proper handling of stdin/stdout for MCP communication.
Development
Contributions are welcome! Please open an issue or submit a pull request if you have any suggestions or improvements.
This project uses uv
to manage dependencies. Install uv
following the instructions for your platform:
curl -LsSf https://astral.sh/uv/install.sh | sh
You can then create a virtual environment and install the dependencies with:
uv venv
source .venv/bin/activate # On Unix/macOS
.venv\Scripts\activate # On Windows
uv pip install -e .
Project Structure
The project has been organized with a src
directory structure:
prometheus-mcp-server/
├── src/
│ └── prometheus_mcp_server/
│ ├── __init__.py # Package initialization
│ ├── server.py # MCP server implementation
│ ├── main.py # Main application logic
├── Dockerfile # Docker configuration
├── docker-compose.yml # Docker Compose configuration
├── .dockerignore # Docker ignore file
├── pyproject.toml # Project configuration
└── README.md # This file
Testing
The project includes a comprehensive test suite that ensures functionality and helps prevent regressions.
Run the tests with pytest:
# Install development dependencies
uv pip install -e ".[dev]"
# Run the tests
pytest
# Run with coverage report
pytest --cov=src --cov-report=term-missing
Tests are organized into:
- Configuration validation tests
- Server functionality tests
- Error handling tests
- Main application tests
When adding new features, please also add corresponding tests.
Tools
Tool | Category | Description |
---|---|---|
execute_query |
Query | Execute a PromQL instant query against Prometheus |
execute_range_query |
Query | Execute a PromQL range query with start time, end time, and step interval |
list_metrics |
Discovery | List all available metrics in Prometheus |
get_metric_metadata |
Discovery | Get metadata for a specific metric |
get_targets |
Discovery | Get information about all scrape targets |
License
MIT
Leave a Comment
Frequently Asked Questions
What is MCP?
MCP (Model Context Protocol) is an open protocol that standardizes how applications provide context to LLMs. Think of MCP like a USB-C port for AI applications, providing a standardized way to connect AI models to different data sources and tools.
What are MCP Servers?
MCP Servers are lightweight programs that expose specific capabilities through the standardized Model Context Protocol. They act as bridges between LLMs like Claude and various data sources or services, allowing secure access to files, databases, APIs, and other resources.
How do MCP Servers work?
MCP Servers follow a client-server architecture where a host application (like Claude Desktop) connects to multiple servers. Each server provides specific functionality through standardized endpoints and protocols, enabling Claude to access data and perform actions through the standardized protocol.
Are MCP Servers secure?
Yes, MCP Servers are designed with security in mind. They run locally with explicit configuration and permissions, require user approval for actions, and include built-in security features to prevent unauthorized access and ensure data privacy.
Related MCP Servers
sylphlab pdf reader mcp
An MCP server built with Node.js/TypeScript that allows AI agents to securely read PDF files (local or URL) and extract text, metadata, or page counts. Uses pdf-parse.
aashari mcp server atlassian bitbucket
Node.js/TypeScript MCP server for Atlassian Bitbucket. Enables AI systems (LLMs) to interact with workspaces, repositories, and pull requests via tools (list, get, comment, search). Connects AI directly to version control workflows through the standard MCP interface.
aashari mcp server atlassian confluence
Node.js/TypeScript MCP server for Atlassian Confluence. Provides tools enabling AI systems (LLMs) to list/get spaces & pages (content formatted as Markdown) and search via CQL. Connects AI seamlessly to Confluence knowledge bases using the standard MCP interface.
weibaohui k8m
一款轻量级、跨平台的 Mini Kubernetes AI Dashboard,支持大模型+智能体+MCP(支持设置操作权限),集成多集群管理、智能分析、实时异常检测等功能,支持多架构并可单文件部署,助力高效集群管理与运维优化。
watchdealer pavel watchbase mcp server
MCP Server for structured and standardized querying of watch-related metadata such as brands, families, and reference details from WatchBase.com.
vgnshiyer apple books mcp
Apple Books MCP Server
ttiimmaacc cinema4d mcp
Cinema 4D plugin integrating Claude AI for prompt-driven 3D modeling, scene creation, and manipulation.
sv mcp paradex py
Connect AI agents to the Paradex trading platform. Retrieve market data, manage accounts, and execute trades seamlessly. Enhance your trading experience with automated tools and real-time insights.
SamllPigYanDong revit mcp
Revit MCP. A Model Context Protocol server for Revit integration, enabling seamless communication between Claude AI and Autodesk Revit.
Rayyan9477 linkedin mcp
A powerful Model Context Protocol server for LinkedIn interactions that enables AI assistants to search for jobs, generate resumes and cover letters, and manage job applications programmatically.
Submit Your MCP Server
Share your MCP server with the community
Submit Now