prometheus

The Prometheus MCP Server exposes the Prometheus HTTP API as a tool-accessible interface for LLMs. It registers a suite of Prometheus endpoints (such as query, range_query, label_names, label_values, metric_metadata, targets_metadata, list_targets, and more) so an LLM can programmatically query and analyze metrics, configuration, and runtime information from a running Prometheus instance. Additionally, the server provides documentation-reading tools (docs_list, docs_read, docs_search) to help the model fetch Prometheus documentation and best practices, and it can optionally enable TSDB admin tools for advanced data management via dedicated endpoints. By default, a core set of tools is always loaded to keep interactions efficient, while additional tools can be enabled via flags to tailor the capabilities to your use case.

To use the MCP server, start the server process and then issue tool calls (e.g., query, range_query) through your desired interface. If you need to reduce token usage, you can enable TOON-encoded output or apply an output truncation limit. You can also whitelist specific tools at startup with the --mcp.tools flag to limit the LLM’s tool surface to only those you want to expose.

Prerequisites:

• A host machine with a supported OS and network access to the Prometheus instance you will query
• Optional: Go toolchain if you build from source, otherwise a prebuilt binary is sufficient
• Access to the Prometheus API endpoint you will query (default: http://localhost:9090)

Installation options:

1. Download a prebuilt binary

   • Visit the Prometheus MCP Server release page for the latest release and download the binary named for your OS/architecture.
   • Make it executable: chmod +x prome
   • Move it to a directory in your PATH, e.g.: mv prome /usr/local/bin/

2. Build from source (Go)

   • Ensure Go is installed: https://golang.org/dl/
   • Clone the repository and navigate into it: git clone https://github.com/tjhop/prometheus-mcp-server.git cd prometheus-mcp-server
   • Build the binary: go build -o prome ./...
   • Confirm the binary is created: ls -l prome

3. Basic run to start the MCP server

   • Start the server (adjust Prometheus URL if needed): prome
   • If you want to enable specific tool sets or additional behavior, pass flags as documented in the README (e.g., --mcp.tools to whitelist tools, enable TOON encoding, or enable TSDB admin endpoints with the dangerous flag). Example: prome --mcp.tools docs_list,query,range_query --flags

Notes:

• Ensure network access from the MCP server to your Prometheus instance. If Prometheus is secured, configure appropriate auth headers or endpoints.
• If you plan to enable TSDB Admin tools, be aware of the potential destructive operations and use the dedicated flag as described in the docs.

Tips and common considerations:

• The MCP server exposes a broad set of tools for querying and analyzing metrics. If you’re new to Prometheus, start with core tools like query, range_query, metric_metadata, label_names, label_values, and series to understand metric shapes and identities.
• You can restrict the tool surface at startup using --mcp.tools to reduce context and improve performance for LLMs with smaller context windows.
• To reduce token usage, consider enabling TOON output and using the API response truncation feature (set a non-zero truncation limit) if available via flags.
• If you enable TSDB admin tools, understand the risks: operations like delete_series and snapshot can modify or remove data. Ensure appropriate access controls and backups.
• Environment variables related to flags and encoding can be used to fine-tune behavior. Refer to the tool flags documentation to know exact variable names and usage.