How yanmxa/prometheus-mcp-server works
Project Type and Purpose
• This is a backend CLI-based MCP (Model Context Protocol) server implemented in TypeScript.
• Its job is to expose a set of “tools” (prom_query, prom_range, prom_discover, etc.) over the MCP protocol and translate them into Prometheus HTTP API calls.
File Structure
• Top level: package.json, tsconfig.json, README.md, .env.example
• src/index.ts – CLI entrypoint & MCP protocol bootstrap
• src/tools.ts – Implements each MCP “tool” handler
• src/prometheus-client.ts – HTTP client wrapper for Prometheus endpoints
Core Architectural Components
a. CLI / MCP Server (index.ts)
• Reads environment variables (PROMETHEUS_URL, auth, timeouts)
• Registers MCP commands (tools) and dispatches calls
b. Tools Layer (tools.ts)
• Business logic for each “tool”: prom_query, prom_range, prom_discover, etc.
• Parses incoming MCP requests, calls the client, formats responses
c. Prometheus HTTP Client (prometheus-client.ts)
• Provides typed methods to hit Prometheus’s REST API (instant, range, metadata, targets)
• Handles authentication (basic, bearer token, TLS settings)
d. Environment Configuration
• .env or environment variables injected into startup
• Drives client behavior (URL, credentials, timeout, insecure TLS)
e. External Service
• Prometheus server (http://localhost:9090 or remote)
Relationships & Data Flow
1) Operator invokes npx prometheus-mcp-server (or global install).
2) MCP server (index.ts) starts, reads config, exposes MCP protocol endpoint.
3) AI assistant or client sends an MCP request to a specific tool (e.g., prom_query).
4) MPC server routes request → Tools Layer.
5) Tool handler calls Prometheus HTTP Client → makes REST API call to Prometheus.
6) HTTP Client returns JSON data → Tool formats result → MCP server returns response.
Architectural Patterns & Design Principles
• Separation of Concerns:
• index.ts only handles protocol registration & config
• tools.ts only handles tool-specific logic
• prometheus-client.ts only handles HTTP communication
• Plug-in / Extensible Tools: Each tool is a self-contained function; new tools can be added with minimal changes.
• Type Safety: End-to-end TypeScript types define all requests/responses.
Putting It All Together
• Layer 1 (left): Client / AI assistant talking over MCP protocol
• Layer 2: MCP Server (index.ts) reading Env Config
• Layer 5 (right): Prometheus Server (HTTP API)