Overview

This TypeScript MCP (Model Context Protocol) server provides a bridge between AI assistants and Prometheus, letting an LLM-powered assistant run Prometheus queries using natural language. The server implements the MCP tool interface so assistants that understand MCP can list tools, inspect tool schemas, and invoke a Prometheus query tool. It can either accept PromQL directly or translate plain-English queries into PromQL via a configured LLM.

For developers, this server is useful when you want to add observability queries to conversational agents, chatops bots, or internal tools. Instead of teaching an assistant PromQL, you expose a single, well-typed tool (for example, prometheus_query) that accepts a short description (or PromQL) and returns query results. The TypeScript implementation is straightforward to extend and integrate into existing MCP-enabled stacks.

Features

MCP-compatible tool registration and invocation for Prometheus queries
Support for instant and range queries (Prometheus /api/v1/query and /api/v1/query_range)
Optional Natural Language → PromQL translation via an LLM (configurable)
TypeScript codebase easy to extend and type-safe
Simple environment-based configuration (Prometheus URL, port, LLM keys)
Returns Prometheus JSON responses so callers can post-process or visualize results

Installation / Configuration

Clone the repository and install dependencies:

git clone https://github.com/yanmxa/prometheus-mcp-server.git
cd prometheus-mcp-server
npm install

Development and build commands:

# Run in development (hot reload)
npm run dev

# Build and run the compiled server
npm run build
npm start

Environment variables (example .env):

# Prometheus server base URL (required)
PROMETHEUS_URL=https://prometheus.example.net

# Port the MCP server listens on (optional)
PORT=8080

# Optional: LLM provider configuration for NL->PromQL translation
LLM_PROVIDER=openai
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxx

# Optional: Toggle automatic NL translation
ENABLE_NL_TRANSLATION=true

Place the .env file in the project root or export variables in your runtime environment. If you do not configure an LLM, the tool will accept explicit PromQL strings and forward them directly to Prometheus.

Available Tools / Resources

The server exposes an MCP tool for querying Prometheus. Typical metadata and endpoints exposed to an MCP-aware assistant include:

Tool name: prometheus_query
Description: Run Prometheus instant or range queries; accepts NL descriptions if translation is enabled
Parameters:
- mode: “instant” | “range”
- query: string (PromQL or natural language if translation is enabled)
- start: ISO timestamp (required for range)
- end: ISO timestamp (required for range)
- step: duration (e.g., “60s”) for range queries

Common MCP HTTP endpoints (implementation may vary slightly; check the repo for exact paths):

Method	Path	Purpose
GET	/mcp/1/tools	List registered MCP tools
POST	/mcp/1/tools/:id/invoke	Invoke a registered tool
GET	/health	Health check

Responses are the raw Prometheus API JSON objects from /api/v1/query or /api/v1/query_range so clients can interpret vector/matrix results.

Use Cases

ChatOps: Integrate with an assistant in Slack or MS Teams so engineers can ask “What was the average request latency for service X over the last 2 hours?” The assistant calls the MCP tool; the server converts the phrase to PromQL (if enabled) and returns series or chart-ready data.
Incident response: During an alert investigation, an assistant can run follow-up queries like “Show error rate for backend pods in the last 30 minutes” without requiring the user to write PromQL.
Internal dashboards: Use the MCP server as a backend that generates query results from conversational input to populate ad-hoc dashboards or notebooks.
Automation scripts: Programmatically invoke the prometheus_query tool from automation workflows to enrich runbook steps with live metrics.

Example invocation (curl-like pseudo-request):

curl -X POST "http://localhost:8080/mcp/1/tools/prometheus_query/invoke" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "range",
    "query": "average CPU usage for service=web over the last 6 hours",
    "start": "2026-04-09T00:00:00Z",
    "end": "2026-04-09T06:00:00Z",
    "step": "60s"
  }'

The server will either (a) translate the description to a PromQL expression and run /api/v1/query_range, or (b) forward the provided PromQL directly if a PromQL string was supplied. The response contains Prometheus result data in standard JSON format.

Extending and Best Practices

If you enable NL→PromQL translation, tune the LLM prompts and examples to match your metric naming and label conventions to improve accuracy.
Use role-based network controls to restrict access to the MCP server; it allows running arbitrary queries against Prometheus.
Cache or rate-limit expensive range queries to protect your Prometheus instance.
Extend the tool schema to include metadata (e.g., allowed metric namespaces) so downstream assistants can validate user requests before invoking queries.

Repository and source code: https://github.com/yanmxa/prometheus-mcp-server

Prometheus TypeScript MCP Server for Natural Language Queries