idanfishman/prometheus-mcp

Prometheus MCP Server

Key Features

• Fast and lightweight. Direct API integration with Prometheus, no complex parsing needed.
• LLM-friendly. Structured JSON responses optimized for AI assistant consumption.
• Configurable capabilities. Enable/disable tool categories based on your security and operational requirements.
• Dual transport support. Works with both stdio and HTTP transports for maximum compatibility.

Requirements

• Node.js 20.19.0 or newer
• Access to a Prometheus server
• VS Code, Cursor, Windsurf, Claude Desktop or any other MCP client

Getting Started

First, install the Prometheus MCP server with your client. A typical configuration looks like this:

{
  "mcpServers": {
    "prometheus": {
      "command": "npx",
      "args": ["prometheus-mcp@latest", "stdio"],
      "env": {
        "PROMETHEUS_URL": "http://localhost:9090"
      }
    }
  }
}

Configuration

Prometheus MCP server supports the following arguments. They can be provided in the JSON configuration above, as part of the "args" list:

> npx prometheus-mcp@latest --help

Commands:
  stdio  Start Prometheus MCP server using stdio transport
  http   Start Prometheus MCP server using HTTP transport

Options:
  --help     Show help                          [boolean]
  --version  Show version number                [boolean]

Environment Variables

You can also configure the server using environment variables:

• PROMETHEUS_URL - Prometheus server URL
• ENABLE_DISCOVERY_TOOLS - Set to “false” to disable discovery tools (default: true)
• ENABLE_INFO_TOOLS - Set to “false” to disable info tools (default: true)
• ENABLE_QUERY_TOOLS - Set to “false” to disable query tools (default: true)

Standalone MCP Server

When running in server environments or when you need HTTP transport, run the MCP server with the http command:

npx prometheus-mcp@latest http --port 3000

And then in your MCP client config, set the url to the HTTP endpoint:

{
  "mcpServers": {
    "prometheus": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:3000/mcp"]
    }
  }
}

Docker

Run the Prometheus MCP server using Docker:

{
  "mcpServers": {
    "prometheus": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--init",
        "--pull=always",
        "-e",
        "PROMETHEUS_URL=http://host.docker.internal:9090",
        "ghcr.io/idanfishman/prometheus-mcp",
        "stdio"
      ]
    }
  }
}

Tools

The Prometheus MCP server provides 10 tools organized into three configurable categories:

Example Usage

Here are some example interactions you can have with your AI assistant:

Basic Queries

• “Show me all available metrics in Prometheus”
• “What’s the current CPU usage across all instances?”
• “Get the memory usage for the last hour”

Discovery and Exploration

• “List all scrape targets and their status”
• “What labels are available for the http_requests_total metric?”
• “Show me all metrics related to ‘cpu’”

Advanced Analysis

• “Compare CPU usage between production and staging environments”
• “Show me the top 10 services by memory consumption”
• “What’s the error rate trend for the API service over the last 24 hours?”

Security Considerations

• Network Access: The server requires network access to your Prometheus instance
• Resource Usage: Range queries can be resource-intensive; monitor your Prometheus server load

Troubleshooting

Connection Issues

• Verify your Prometheus server is accessible at the configured URL
• Check firewall settings and network connectivity
• Ensure Prometheus API is enabled (default on port 9090)

Permission Errors

• Verify the MCP server has network access to Prometheus
• Check if authentication is required for your Prometheus setup

Tool Availability

• If certain tools are missing, check if they’ve been disabled via configuration

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• GitHub Issues: Report bugs or request features
• Documentation: Model Context Protocol Documentation
• Prometheus: Prometheus Documentation

Built with ❤️ for the Prometheus and MCP communities