# grafana/mcp-grafana architecture

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

- Interactive diagram: https://gitdiagram.com/grafana/mcp-grafana
- Repository: https://github.com/grafana/mcp-grafana

## Overview

##### Project Type and Purpose
- This is a Go-based server project that implements the Model Context Protocol (MCP) for Grafana. Its purpose is to serve as a bridge for clients (like Claude Desktop) to interact with Grafana’s dashboards, datasources, alerting, incidents, and metric/query information.
- The README shows that the server exposes multiple “tools” (functional endpoints) to search and retrieve dashboards, query datasource information for Prometheus, Loki, etc., and manage incidents in Grafana.

##### File Structure
- The top-level files (Dockerfile, docker-compose.yaml, Makefile) and .github workflows indicate that the project is containerized and has CI/CD pipelines.
- The “cmd” directory contains the main entry point (cmd/mcp-grafana/main.go), which indicates that the core server is compiled into a single binary.
- The “tools” directory and corresponding test files suggest that various “tools” (or handlers) are modularized as packages, each handling a specific functionality (alerting, dashboards, datasources, incidents, etc.).
- The “testdata” directory includes configurations and provisioning files for dashboards, datasources, and alerting rules, modelling an environment for integration tests against a Grafana instance.
- Additional configuration files (Docker configurations, CI workflows) reflect the need for containerized deployment and automated testing.

##### Main Components and Their Relationships
a. Entry Point (Server Binary):
- Represented by the main.go file under the “cmd/mcp-grafana” directory.
- This component is responsible for launching the MCP server that listens for incoming requests.
b. Tools/Service Modules:
- Each tool (like search_dashboards, get_dashboard_by_uid, list_datasources, etc.) corresponds to a module or package (found in the “tools” directory).
- These components encapsulate business logic related to Grafana’s functionalities.
c. Configuration and Environment:
- The server gets started with environment variables (e.g., GRAFANA_URL, GRAFANA_API_KEY) as described in the README.
- External configuration comes into play when setting up integrations with Grafana (or possibly with other monitoring systems like Prometheus or Loki).
d. External Integration Points:
- Grafana Instance: The server communicates with a Grafana instance (which could be run locally or in a container, as shown by docker-compose.yaml) to perform operations like dashboard searches, incident management, and datasource queries.
- Other Services: Tools for various publicity designated integrations (Prometheus, Loki, Tempo, etc.) hint at dependencies on these systems for fetching metadata and executing queries.
e. Development & CI/CD Infrastructure:
- With workflows defined in .github/workflows and build/deployment scripts in Makefile and Dockerfile, there’s an automation layer for building, testing, and deploying the service.

##### Architectural Patterns and Design Principles
- Modular Design: The separation between the main server code (cmd) and the specific tool functionalities (tools/) suggests a modular, possibly plugin-oriented architecture.
- Service Separation: Although it is a single binary, the internal components can be seen as distinct “services” or endpoints that handle different requests.
- Containerization & CI/CD: The use of Docker, docker-compose, and GitHub workflows indicates that the project emphasizes deployment automation and consistent testing environments.

##### Final Recommendations
- Be as detailed as possible: if a tool or module exists, include it as a specific component rather than lumping everything into “business logic.”
- Not only the data flow between the client, server, and external systems, but also the development and deployment lifecycle, which is crucial for maintainability and traceability.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        Client["MCP Client"]:::external
    end

    %% Server Layer
    subgraph "Server Layer"
        Config["Configuration & Environment"]:::config
        Server["MCP Server Binary"]:::server
        Dashboard["Dashboard Tools Module"]:::module
        Datasources["Datasource Tools Module"]:::module
        Alerting["Alerting Tools Module"]:::module
        Incidents["Incidents Management Module"]:::module
        Loki["Loki Logs Integration Module"]:::module
        PromQuery["Prometheus Query Module"]:::module
        Search["Search Functionality Module"]:::module

        %% Module Tests sub-section
        DashboardTest["Dashboard Tools Tests"]:::test
        DatasourcesTest["Datasources Tools Tests"]:::test
        AlertingTest["Alerting Tools Tests"]:::test
        IncidentsTest["Incidents Tools Tests"]:::test
        LokiTest["Loki Logs Tests"]:::test
        PromQueryTest["Prometheus Query Tests"]:::test
        SearchTest["Search Functionality Tests"]:::test
    end

    %% External Services
    subgraph "External Services"
        Grafana["Grafana Instance"]:::external
        Prometheus["Prometheus"]:::external
        LokiService["Loki"]:::external
    end

    %% CI/CD & Infrastructure
    subgraph "CI/CD & Infrastructure"
        Docker["Dockerfile"]:::infrastructure
        DockerCompose["docker-compose.yaml"]:::infrastructure
        Makefile["Makefile"]:::infrastructure
        GitHubBuild[".github/workflows/build-image.yml"]:::infrastructure
        GitHubGo[".github/workflows/go.yml"]:::infrastructure
        GitHubRelease[".github/workflows/release.yml"]:::infrastructure
        TestData["Test Data (testdata/)"]:::infrastructure
    end

    %% Connections between layers
    Client -->|"calls"| Server
    Config -->|"provides_env"| Server

    Server -->|"loads"| Dashboard
    Server -->|"loads"| Datasources
    Server -->|"loads"| Alerting
    Server -->|"loads"| Incidents
    Server -->|"loads"| Loki
    Server -->|"loads"| PromQuery
    Server -->|"loads"| Search

    Dashboard -->|"tested_by"| DashboardTest
    Datasources -->|"tested_by"| DatasourcesTest
    Alerting -->|"tested_by"| AlertingTest
    Incidents -->|"tested_by"| IncidentsTest
    Loki -->|"tested_by"| LokiTest
    PromQuery -->|"tested_by"| PromQueryTest
    Search -->|"tested_by"| SearchTest

    %% Module External Interactions
    Dashboard -->|"retrieves"| Grafana
    Alerting -->|"manages"| Grafana
    Incidents -->|"handles"| Grafana
    Datasources -->|"queries"| Grafana
    Search -->|"searches"| Grafana
    PromQuery -->|"queries"| Prometheus
    Loki -->|"queries"| LokiService

    %% CI/CD deployments and integration
    Docker -->|"builds_image"| Server
    DockerCompose -->|"orchestrates"| Server
    Makefile -->|"triggers_build"| Server
    GitHubBuild -->|"CI_build"| Server
    GitHubGo -->|"CI_test"| Server
    GitHubRelease -->|"deploys"| Server
    TestData -->|"integration_conf"| Grafana

    %% Styles
    classDef server fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef module fill:#B0E0E6,stroke:#333,stroke-width:2px;
    classDef test fill:#FFEFD5,stroke:#333,stroke-width:2px;
    classDef external fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef config fill:#D3D3D3,stroke:#333,stroke-width:2px;
    classDef infrastructure fill:#90EE90,stroke:#333,stroke-width:2px;

    %% Click Events for Components
    click Server "https://github.com/grafana/mcp-grafana/blob/main/cmd/mcp-grafana/main.go"
    click Dashboard "https://github.com/grafana/mcp-grafana/blob/main/tools/dashboard.go"
    click Datasources "https://github.com/grafana/mcp-grafana/blob/main/tools/datasources.go"
    click Alerting "https://github.com/grafana/mcp-grafana/blob/main/tools/alerting.go"
    click Incidents "https://github.com/grafana/mcp-grafana/blob/main/tools/incident.go"
    click Loki "https://github.com/grafana/mcp-grafana/blob/main/tools/loki.go"
    click PromQuery "https://github.com/grafana/mcp-grafana/blob/main/tools/prometheus.go"
    click Search "https://github.com/grafana/mcp-grafana/blob/main/tools/search.go"
    click DashboardTest "https://github.com/grafana/mcp-grafana/blob/main/tools/dashboard_test.go"
    click DatasourcesTest "https://github.com/grafana/mcp-grafana/blob/main/tools/datasources_test.go"
    click AlertingTest "https://github.com/grafana/mcp-grafana/blob/main/tools/alerting_test.go"
    click IncidentsTest "https://github.com/grafana/mcp-grafana/blob/main/tools/incident_test.go"
    click GitHubRelease "https://github.com/grafana/mcp-grafana/blob/main/tools/incident_integration_test.go"
    click LokiTest "https://github.com/grafana/mcp-grafana/blob/main/tools/loki_test.go"
    click PromQueryTest "https://github.com/grafana/mcp-grafana/blob/main/tools/prometheus_test.go"
    click SearchTest "https://github.com/grafana/mcp-grafana/blob/main/tools/search_test.go"
    click TestData "https://github.com/grafana/mcp-grafana/tree/main/testdata/"
    click Docker "https://github.com/grafana/mcp-grafana/tree/main/Dockerfile"
    click DockerCompose "https://github.com/grafana/mcp-grafana/blob/main/docker-compose.yaml"
    click Makefile "https://github.com/grafana/mcp-grafana/tree/main/Makefile"
    click GitHubBuild "https://github.com/grafana/mcp-grafana/blob/main/.github/workflows/build-image.yml"
    click GitHubGo "https://github.com/grafana/mcp-grafana/blob/main/.github/workflows/go.yml"
    click GitHubRelease "https://github.com/grafana/mcp-grafana/blob/main/.github/workflows/release.yml"
```
