prometheus

This Prometheus MCP Server is a Go-based MCP server that communicates with a Prometheus server using SSE (server-sent events). It exposes a set of MCP tools to discover metrics, inspect metadata, and run queries against Prometheus. The server supports basic auth, token auth, or no auth depending on the environment variables you supply. To use it, run the Docker command provided in the mcp_config section (or deploy in your preferred environment) and ensure PROMETHEUS_URL points to your Prometheus instance. The MCP tools available include: prometheus_list_metrics to list available metrics, prometheus_get_targets to discover and explore metrics targets, prometheus_get_metric_metadata to fetch metadata for a specific metric, prometheus_execute_query to run immediate queries, prometheus_execute_range_query for range queries across a time window, and prometheus_execute_last_query to view recent query results. The server streams data via SSE by default, but you can switch to stdio mode by setting MCP_SERVER_TRANSPORT to stdio in your environment. When configuring clients, you can reference the SSE endpoint URL exposed by the server (for example, the /sse path) to connect and begin querying Prometheus metrics.

Prerequisites:

• Docker installed and running on the host
• Access to a Prometheus server to monitor

Installation steps:

1. Ensure Docker is installed on your machine. Verify:

   docker --version

2. Pull and run the Prometheus MCP Server container (example using SSE):

   docker run -d --name prometheus-mcp-server
   -e PROMETHEUS_URL=http://your-prometheus-server:9090
   -e MCP_SERVER_TRANSPORT=sse
   shaxiaozz/prometheus-mcp-server:latest

   This starts the MCP server in SSE mode and points it at your Prometheus instance. You can customize authentication by supplying additional environment variables as needed (see mcp_config env section).

3. Verify the container is running and note the log URL for the SSE endpoint if needed:

   docker logs prometheus-mcp-server

4. Optional: If you need stdio mode, set MCP_SERVER_TRANSPORT=stdio in the environment and redeploy the container.

5. Configure a MCP client (e.g., Cursor Desktop or another MCP client) with the server URL to start using the available MCP tools.

Tips and common issues:

• Ensure PROMETHEUS_URL is reachable from the MCP server container. Networking between containers or from the host to Prometheus must be allowed.
• If Prometheus uses authentication, provide PROMETHEUS_USERNAME and/or PROMETHEUS_PASSWORD or PROMETHEUS_TOKEN as appropriate.
• In SSE mode, the client should listen to the /sse endpoint exposed by the server. If you switch to stdio mode, the transport mechanism changes and you may need to adjust client settings.
• The server configuration example shows a default container name (prometheus-mcp-server). If you reuse the container name, ensure you remove a previously running container with the same name.
• The MCP tools (prometheus_list_metrics, prometheus_get_targets, prometheus_get_metric_metadata, prometheus_execute_query, prometheus_execute_range_query, prometheus_execute_last_query) are the primary capabilities you’ll use to explore and query Prometheus metrics.
• You can modify the environment variables at deployment time to adjust authentication methods or to point to different Prometheus instances.