Prometheus MCP Server
About
A Prometheus MCP server with full API support for comprehensive management and deep interaction with Prometheus beyond basic query support. Written in go, it is a single binary install that is capable of STDIO, SSE, and HTTP transports for complex deployments.
Explore
If you use](#command-line-flags)DevboxandDirenv, then simply entering the directory for the repo should set up the needed software.
Seemcp.jsonfor an example MCP config for use with tooling. Requiresollamato be installed.
To override the default LLM (ollama:gpt-oss:20b), runexport OLLAMA_MODEL="ollama:your_model"to override it before runningmake.
Seesettings.jsonfor an example config file to run gemini-cli with the prometheus-mcp-server. Requiresgemini-clito be installed.
- Working Go environment
- Docker for local tests/linting/image building/etc
- GNU Make
- ollama
- mcp inspector
- mcphost
This project uses the standard Prometheus build tooling:promudriven throughMakefile/Makefile.common. The binary embeds a pinned snapshot ofprometheus/docs, which the build targets download and extract automatically (the pin lives inDOCS_VERSIONin theMakefile).
make build # build the binary for the host platform (via promu) make test # run the test suite make crossbuild # build binaries for all release platforms make # run the full check suite: style, license, yamllint, lint, build, test
Project-specific helper targets (helm packaging and the local LLM client integrations) are listed bymake help:
make help Usage: make <target> Project targets: help print this help message (see Makefile.common for the standard prometheus targets) docs download and extract the pinned prometheus/docs snapshot for embedding helm-sync-dashboards copy grafana dashboards into helm chart for packaging helm-lint run helm chart linting helm-template render helm templates for inspection helm-test install helm chart and run tests (requires a running cluster) mcphost use mcphost to run the prometheus-mcp-server against a local ollama model inspector use inspector to run the prometheus-mcp-server in STDIO transport mode inspector-http use inspector to run the prometheus-mcp-server in streamable HTTP transport mode open-webui use open-webui to run the prometheus-mcp-server gemini use gemini-cli to run the prometheus-mcp-server against Google Gemini models
The available command line flags are documented in the help flag:
~/go/src/github.com/tjhop/prometheus-mcp-server (main [ ]) -> ./prometheus-mcp-server --help usage: prometheus-mcp-server [<flags>] Flags: -h, --[no-]help Show context-sensitive help (also try --help-long and --help-man). ($PROMETHEUS_MCP_SERVER_HELP) --mcp.tools=all ... List of mcp tools to load. The target all can be used to load all tools. The target core loads only the core tools: docs_list,docs_read,docs_search,runbooks_list,runbooks_read,query,range_query,metric_metadata,label_names,label_values,series Otherwise, it is treated as an allow-list of tools to load, in addition to the core tools. Please see project README for more information and the full list of tools. ($PROMETHEUS_MCP_SERVER_MCP_TOOLS) --[no-]mcp.enable-toon-output Enable Token-Oriented Object Notation (TOON) output for tools instead of JSON ($PROMETHEUS_MCP_SERVER_MCP_ENABLE_TOON_OUTPUT) --[no-]mcp.enable-client-logging Enable sending log messages to connected MCP clients as protocol notifications. When enabled, tool execution logs are sent both to the server's primary log output and to the MCP client, allowing LLMs to observe server activity. ($PROMETHEUS_MCP_SERVER_MCP_ENABLE_CLIENT_LOGGING) --mcp.transport="stdio" The type of transport to use for the MCP server [stdio, http]. ($PROMETHEUS_MCP_SERVER_MCP_TRANSPORT) --prometheus.backend=PROMETHEUS.BACKEND Customize the toolset for a specific Prometheus API compatible backend. Supported backends include: prometheus,thanos ($PROMETHEUS_MCP_SERVER_PROMETHEUS_BACKEND) --prometheus.url="http://127.0.0.1:9090" URL of the Prometheus instance to connect to ($PROMETHEUS_MCP_SERVER_PROMETHEUS_URL) --prometheus.timeout=1m Timeout for API calls to the Prometheus backend ($PROMETHEUS_MCP_SERVER_PROMETHEUS_TIMEOUT) --prometheus.truncation-limit=0 If enabled, this controls the maximum query response size in number of lines/entries provided to the LLM from the API response. LLMs can override truncation limits if needed on a per-tool-call basis via tool request arguments on supported tools. To disable truncation limits, set to 0. ($PROMETHEUS_MCP_SERVER_PROMETHEUS_TRUNCATION_LIMIT) --http.config=HTTP.CONFIG Path to config file to set Prometheus HTTP client options ($PROMETHEUS_MCP_SERVER_HTTP_CONFIG) --web.telemetry-path="/metrics" Path under which to expose metrics. ($PROMETHEUS_MCP_SERVER_WEB_TELEMETRY_PATH) --web.max-requests=40 Maximum number of parallel scrape requests. Use 0 to disable. ($PROMETHEUS_MCP_SERVER_WEB_MAX_REQUESTS) --[no-]dangerous.enable-tsdb-admin-tools Enable and allow using tools that access Prometheus' TSDB Admin API endpoints (snapshot, delete_series, and clean_tombstones tools). This is dangerous, and allows for destructive operations like deleting data. It is not the fault of this MCP server if the LLM you're connected to nukes all your data. Docs: https://prometheus.io/docs/prometheus/latest/querying/api/#tsdb-admin-apis ($PROMETHEUS_MCP_SERVER_DANGEROUS_ENABLE_TSDB_ADMIN_TOOLS) --[no-]docs.auto-update Enable automatic documentation updates from the official prometheus/docs repository. Checks every 24h0m0s. ($PROMETHEUS_MCP_SERVER_DOCS_AUTO_UPDATE) --log.file=LOG.FILE The name of the file to log to (file rotation policies should be configured with external tools like logrotate) ($PROMETHEUS_MCP_SERVER_LOG_FILE) --[no-]web.systemd-socket Use systemd socket activation listeners instead of port listeners (Linux only). ($PROMETHEUS_MCP_SERVER_WEB_SYSTEMD_SOCKET) --web.listen-address=:8080 ... Addresses on which to expose metrics and web interface. Repeatable for multiple addresses. Examples: :9100 or [::1]:9100 for http, vsock://:9100 for vsock ($PROMETHEUS_MCP_SERVER_WEB_LISTEN_ADDRESS) --web.config.file="" Path to configuration file that can enable TLS or authentication. See: https://github.com/prometheus/exporter-toolkit/blob/master/docs/web-configuration.md ($PROMETHEUS_MCP_SERVER_WEB_CONFIG_FILE) --log.level=info Only log messages with the given severity or above. One of: [debug, info, warn, error] ($PROMETHEUS_MCP_SERVER_LOG_LEVEL) --log.format=logfmt Output format of log messages. One of: [logfmt, json] ($PROMETHEUS_MCP_SERVER_LOG_FORMAT) --[no-]version Show application version. ($PROMETHEUS_MCP_SERVER_VERSION)
Retrieve and analyze time-series data from Prometheus databases using PromQL queries.
Access VictoriaMetrics APIs for monitoring, observability, and debugging.
Access Prometheus metrics and queries through standardized MCP interfaces.
Interact with your Prometheus monitoring infrastructure using natural language.
Expose Prometheus monitoring tools to an LLM for querying and analysis.
An MCP server for integrating with Prometheus to query metrics.
A server for integrating with InfluxDB, a time-series database.
An MCP server for interacting with InfluxDB time-series databases, enabling AI assistants to work with time-series data.
You are working with the MCP MySQL Operations Server, a powerful tool that provides comprehensive MySQL database monitoring and analysis capabilities through natural language queries. This server offers 19 specialized tools for database administration, performance monitoring, and system analysis.
MCP-PostgreSQL-Ops is a professional MCP server for PostgreSQL database operations, monitoring, and management. Supports PostgreSQL 12-17 with comprehensive database analysis, performance monitoring, and intelligent maintenance recommendations through natural language queries.
This is anMCPserver to allow LLMs to interact with a runningPrometheusinstance via the API to do things like generate and execute promql queries, list and analyze metrics, etc.
Asking Claude to Investigate Slow Queries
querying my metrics is slow, can you help me figure out why?
Investigate metrics produced by the MCP server itself and suggest recording rules for SLOs
use the tools from the prometheus mcp server to investigate the metrics from the mcp server and suggest prometheus recording rules for SLOs
Summarize Prometheus metric/label naming best practices
summarize prometheus metric/label name best practices
Report on the health of the Prometheus instance that powers prometheus.demo.prometheus.io
please provide a comprehensive review and summary of the prometheus server. review it's configuration, flags, runtime/build info, and anything else that you feel may provide insight into the status of the prometheus instance, including analyzing metrics and executing queries
The Prometheus HTTP API outputs JSON data, and the tools in this MCP server return that JSON to the LLM for processing as it's structured and well understood by LLMs.
This MCP server supports the following options which have the potential to reduce token/context usage:
If token/context usage is a concern, this MCP server also supports converting the API's JSON data to theToken-Oriented Object Notation (TOON) format. While it is not guaranteed to reduce token usage, it is designed with token efficiency in mind. As noted on TOON's documentation, it excels at uniform arrays of objects; non-uniform/complex objects may still be more token-efficient in JSON. Real world token usage will depend on usage patterns, please review common workflows to determine if TOON output may be beneficial. Please seeFlagsfor more information on the available flags and their corresponding environment variables.
This feature allows you to set a maximum limit on the number of lines or entries returned from the Prometheus API for, which can help in reducing the amount of data sent to the LLM. Setting the limit to0disables truncation. Truncation is disabled by default. Note that LLMs capable of handling tool request arguments can override this global truncation limit on a per-tool-call basis for supported tools. Please seeFlagsfor more information on the available flags and their corresponding environment variables.
The server exposes many tools to interact with Prometheus. There are tools to interact with Prometheus via the API, as well as additional tools to do things like read documentation, etc. By default, they are all registered and available for use (TSDB Admin API tools need an extra flag).
To be considerate to LLMs with smaller context windows, it's possible to pass in a whitelist of specific tools to register with the server. The following 'core' tools are always loaded:[docs_list, docs_read, docs_search, runbooks_list, runbooks_read, query, range_query, metric_metadata, label_names, label_values, series]. Additional tools can be specified with the--mcp.toolsflag.
prometheus-mcp-server --mcp.tools=build_info --mcp.tools=flags --mcp.tools=runtime_info
Would result in the following tools being loaded:
- build_info
- docs_list
- docs_read
- docs_search
- flags
- label_names
- label_values
- metric_metadata
- query
- range_query
- runbooks_list
- runbooks_read
- runtime_info
- series
The server embeds a set of runbooks: guided workflows for common Prometheus tasks, expressed in terms of the server's tools. Each runbook orients the model on the relevant tools, then suggests topics to explore with example queries rather than prescribing a fixed sequence of steps. Runbooks cover tasks like system health checks, missing-data triage, error-rate investigation, high-cardinality optimization, recording/alerting rule review, and configuration/performance tuning.
Each runbook is packaged as a fullAgent Skill: a directory containing aSKILL.mdwithname/descriptionfrontmatter. Runbooks are exposed three ways:
- Tools: the model can discover and read them itself via therunbooks_list/runbooks_readtools when a request matches a runbook's purpose. Tools are the most portable path and work in every MCP client.
- Skill resources: per theSEP-2640 skills extension draft, each runbook is askill://<name>/SKILL.mdresource, enumerated by the well-knownskill://index.jsondiscovery index, and the server declares theio.modelcontextprotocol/skillsextension capability. Skill-aware hosts can consume these like local filesystem skills; other clients can still read them as ordinary MCP resources.
- MCP prompts: each runbook is also registered as anMCP promptunder its skill name (e.g.check-system-health,optimize-high-cardinality), so clients with prompt support can invoke a guided workflow directly (often surfaced as slash commands).
There are many Prometheus compatible backends that can be used to extend prometheus in a variety of ways, often with the goals of offering long term storage or query aggregation from multiple prometheus instances. Some examples can be found in theRemote Storageof prometheus' docs.
Many of those services also offer a "prometheus compatible" API that can be used to query/interact with the data using native promQL. In general, this MCP server should at a minimum work for other prometheus API compatible services to execute queries and interact with the series/labels/metadata endpoints for metric and label discovery. Beyond that, there may be API differences as the different systems implement different parts/extensions of the API for their needs.
- Thanos does not use a centralized config, so the config endpoint is not implemented and thus the config tool fails.
- Mimir and Cortex implement extra endpoints to manage/add/remove rules
To workaround this and provide a better experience on some of the commonly used Prometheus compatible systems, this project may add direct support for select systems to provide different/more tools. Choosing a specific prometheus backend implementation can be done with the--prometheus.backendflag. The list of available backend implementations on a given release of the MCP server can be found in the output of the[--helpflag. Qualifications and support criteria are still under consideration, please open an issue to request support/features for a specific backend for further discussion.
This MCP server is most useful when fully integrated with tooling and/or installed as a tool server with another system. Installation procedures and integration support will vary depending on the tools being used. For example:
- some systems can only interact with MCP tools and not resources/prompts
- some systems use mcp.json config file format to manage MCP servers and some require custom formats
- some systems don't speak MCP directly and require tools like mcp-to-openapi to proxy
Please check the documentation for the tool being used/integrated for specific instructions and level of support.
…
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
