# caesaryangs/prometheus_mcp_server architecture

> Architecture diagram of the GitHub repository caesaryangs/prometheus_mcp_server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/caesaryangs/prometheus_mcp_server
- Repository: https://github.com/caesaryangs/prometheus_mcp_server

## Overview

##### Project type and purpose
- This is a backend-only Python microservice (“MCP Server for Prometheus”) that exposes a Model Context Protocol (MCP) interface, enabling LLMs (e.g., Claude Desktop) to invoke tool-style endpoints for querying and analyzing Prometheus time-series metric data.

##### File structure
Top-level:
- Dockerfile, docker/ (compose + Prometheus scrape config) → containerized deployment
- config.json, smithery.yaml → client integration metadata
- docs/ → usage screenshots and architecture notes
- requirements.txt, pytest.ini → dependencies + test config
- src/prometheus_mcp_server/
– server.py & __main__.py: entrypoint for UVicorn/CLI server
– prometheus_api.py: wrappers over the Prometheus HTTP API
– db_connector.py: data-transformation and caching layer
– pyproject.toml: module metadata
- test/ → unit tests for server and connectors

##### README for additional insights
- Stack: Python, Prometheus API Client (modified), UVicorn (implied), MCP protocol via Smithery integration.
- Deployment options: standalone Python, UV CLI, Docker+Docker-Compose.
- External clients: LLM front-ends (Claude Desktop, Cursor), configured via smithery.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Systems
    subgraph "LLM Client Layer"
        direction TB
        Client["LLM Client Tool (Claude Desktop, Cursor)"]:::external
    end

    %% MCP Server Components
    subgraph "MCP Server"
        direction TB
        Entry["HTTP/CLI Entrypoint\n(server.py)"]:::runtime
        CLI["CLI Entrypoint\n(__main__.py)"]:::runtime
        Router["MCP Protocol Router"]:::runtime
        API["Prometheus API Client\n(prometheus_api.py)"]:::module
        DB["Data Transformation & Caching\n(db_connector.py)"]:::module
        Pack["Module Metadata\n(pyproject.toml)"]:::infra
        Entry -->|invokes| Router
        CLI -->|invokes| Router
        Router -->|calls API| API
        Router -->|calls DB| DB
        API -->|sends PromQL over HTTP| Prometheus
        DB -->|processes & caches data| Prometheus
        API -->|returns raw metrics| DB
        DB -->|returns processed metrics| Router
    end

    %% External Data Store
    subgraph "External Data Store"
        direction TB
        Prometheus["Prometheus TSDB\n(HTTP API)"]:::runtime
    end

    %% Infrastructure & Configuration
    subgraph "Infrastructure & Config"
        direction TB
        DF["Dockerfile"]:::infra
        DC["docker-compose.yml"]:::infra
        YM["prometheus.yml"]:::infra
        SM["smithery.yaml"]:::infra
        CFG["config.json"]:::infra
        REQ["requirements.txt\npytest.ini"]:::infra
    end

    %% Tests & Documentation
    subgraph "Tests & Docs"
        direction TB
        T1["Unit Tests: db_connector\n(test/test_db_connector.py)"]:::infra
        T2["Unit Tests: MCP Server\n(test/test_mcp_server.py)"]:::infra
        DOC["Project Documentation & Architecture\n(docs/)"]:::infra
        T1 -.-> DB
        T2 -.-> Entry
    end

    %% Interactions
    Client -->|MCP JSON-RPC over HTTP/CLI| Entry
    Entry -->|JSON Response| Client

    %% Click Events
    click Entry "https://github.com/caesaryangs/prometheus_mcp_server/blob/main/src/prometheus_mcp_server/server.py"
    click CLI "https://github.com/caesaryangs/prometheus_mcp_server/blob/main/src/prometheus_mcp_server/__main__.py"
    click API "https://github.com/caesaryangs/prometheus_mcp_server/blob/main/src/prometheus_mcp_server/prometheus_api.py"
    click DB "https://github.com/caesaryangs/prometheus_mcp_server/blob/main/src/prometheus_mcp_server/db_connector.py"
    click Pack "https://github.com/caesaryangs/prometheus_mcp_server/blob/main/src/prometheus_mcp_server/pyproject.toml"
    click DF "https://github.com/caesaryangs/prometheus_mcp_server/tree/main/Dockerfile"
    click DC "https://github.com/caesaryangs/prometheus_mcp_server/blob/main/docker/docker-compose.yml"
    click YM "https://github.com/caesaryangs/prometheus_mcp_server/blob/main/docker/prometheus.yml"
    click SM "https://github.com/caesaryangs/prometheus_mcp_server/blob/main/smithery.yaml"
    click CFG "https://github.com/caesaryangs/prometheus_mcp_server/blob/main/config.json"
    click REQ "https://github.com/caesaryangs/prometheus_mcp_server/blob/main/requirements.txt"
    click T1 "https://github.com/caesaryangs/prometheus_mcp_server/blob/main/test/test_db_connector.py"
    click T2 "https://github.com/caesaryangs/prometheus_mcp_server/blob/main/test/test_mcp_server.py"
    click DOC "https://github.com/caesaryangs/prometheus_mcp_server/tree/main/docs/"

    %% Styles
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px
    classDef runtime fill:#87CEEB,stroke:#333,stroke-width:1px
    classDef module fill:#98FB98,stroke:#333,stroke-width:1px
    classDef infra fill:#D3D3D3,stroke:#333,stroke-width:1px
```
