A Model Context Protocol (MCP) server for Prometheus written in Go. This server enables AI assistants to query and analyze Prometheus metrics through standardized MCP interfaces.
- Execute PromQL instant queries
- Execute PromQL range queries over a time period
- Discover series by label matchers
- Explore label names and values
- Access metric metadata
- Get information about scrape targets
- Access alerts and recording rules
- Get Prometheus server status information
- Go 1.20 or higher
- A running Prometheus instance
# Clone the repository
git clone https://github.com/cgoolsby/prometheus-mcp.git
cd prometheus-mcp
# Build the project
go build -o prometheus-mcp ./cmd/server
# Run the server
./prometheus-mcpThe server can be configured using environment variables:
PROMETHEUS_HOST: The base URL of your Prometheus instance (default: http://localhost:9090)
This MCP server can be used with AI assistants that support the Model Context Protocol, such as Claude.
- Add the server configuration to Claude Desktop:
- On macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - On Windows:
%APPDATA%/Claude/claude_desktop_config.json
- On macOS:
{
"mcpServers": {
"prometheus-mcp-server": {
"command": "/path/to/prometheus-mcp",
"env": {
"PROMETHEUS_HOST": "http://your-prometheus-instance:9090"
}
}
}
}The server provides the following functions:
mcp__instant_query: Execute an instant PromQL querymcp__range_query: Execute a range PromQL query over a time periodmcp__get_series: Find series by label matchersmcp__get_label_values: Get values for a specific labelmcp__get_metadata: Get metadata for metricsmcp__get_targets: Get information about scrape targetsmcp__get_alerts: Get information about alertsmcp__get_rules: Get information about recording and alerting rulesmcp__get_status: Get status information about the Prometheus server
# Run tests
go test ./...
# Build the project
go build -o prometheus-mcp ./cmd/server
# Run end-to-end tests
./scripts/e2e_test.sh
# or
make e2e-testThis repository includes pre-commit hooks to ensure code quality. To enable them, run:
git config core.hooksPath .githooksYou can skip the end-to-end tests in the pre-commit hook by setting an environment variable:
SKIP_E2E_TESTS=true git commit -m "Your commit message"A detailed tutorial on how to use the Prometheus MCP server with a local Prometheus instance and Ollama for LLM integration is available in the docs/tutorial.md file.
MIT
├── cmd/ # Command-line applications
│ └── server/ # Main MCP server application
├── docs/ # Documentation
│ └── tutorial.md # Tutorial for using the server
├── examples/ # Example code
│ └── demo.go # Go demo showing MCP server usage
├── internal/ # Internal packages
│ └── server/ # Server implementation
├── pkg/ # Public packages
│ ├── mcp/ # MCP protocol implementation
│ └── prometheus/ # Prometheus client
├── scripts/ # Utility scripts
│ └── e2e_test.sh # End-to-end test script
└── .githooks/ # Git hooks
└── pre-commit # Pre-commit hook for quality checks
Contributions are welcome! Please follow these steps to contribute:
- Fork the repository
- Create a new branch for your feature or bugfix
- Implement your changes
- Add tests for your changes
- Ensure all tests pass (
make testandmake e2e-test) - Commit your changes (the pre-commit hook will run quality checks)
- Push to your branch
- Create a Pull Request
This project follows standard Go coding conventions. Please ensure your code:
- Is formatted with
go fmt - Passes
go vet - Has appropriate comments and documentation
- Includes tests for new functionality
If you find a bug or have a feature request, please create an issue with the following information:
- A clear, descriptive title
- A detailed description of the issue or feature request
- Steps to reproduce the issue (for bugs)
- Expected behavior
- Actual behavior
- Environment information (OS, Go version, Prometheus version)