Grafana MCP Architecture

Grafana MCP is a Model Context Protocol server that enables AI agents to query Grafana dashboards, data sources, and alerts. It wraps the open-source mcp-grafana Python package behind a supergateway SSE bridge, exposing Grafana's full HTTP API as MCP tools that any MCP-compatible client (Claude Code, Gemini CLI, MCP proxies) can invoke.

The server runs as a Docker container on the hosting_web network, communicating with the co-located Grafana instance over internal Docker DNS. It accepts connections via SSE on port 8100 and is reachable at grafana-mcp.home through Traefik.

Part of the MCP Tools Stack — one of four MCP servers (Grafana, Hugging Face, PubMed, Mermaid) deployed together from /home/rod/_rod/_mcp-tools/docker-compose.yml.

Language

Python 3.12

MCP Transport

stdio → SSE

Exposed Port

8100

MCP Tools

Container

grafana-mcp

Network

hosting_web

2. Runtime Architecture

Diagram A — Runtime request flow

Request Flow

Claude Code (or any MCP client) connects to the grafana-mcp container via SSE on port 8100.
supergateway (Node.js) receives the SSE connection and bridges it to the mcp-grafana process over stdio.
mcp-grafana (Python) parses the MCP tool call, authenticates with the Grafana service account token, and issues HTTP requests to the Grafana API.
Grafana responds with dashboard JSON, metric query results, or alert data, which flows back through the same chain.

5. Public Interfaces

MCP Tools

Tool	Description	Parameters	Returns
`list_dashboards`	List all available Grafana dashboards with their UIDs, titles, and folder locations.	None	JSON array of dashboard summaries
`get_dashboard`	Retrieve the full JSON model and metadata for a specific dashboard by UID.	`uid` (string) — Dashboard UID	Dashboard JSON with panels, variables, and annotations
`query_metrics`	Execute a query against a Grafana data source (Prometheus, InfluxDB, etc.) and return results.	`datasource` (string), `query` (string), optional time range	Query result frames (time series or table data)

SSE Endpoint

Endpoint	Method	Description
`http://grafana-mcp:8100/sse`	GET	Server-Sent Events stream for MCP protocol communication. Provided by supergateway.

Component Classification

Component	Classification	Role
`mcp-grafana`	Primary	Core MCP server implementing Grafana tool handlers
`supergateway`	Secondary	stdio-to-SSE transport bridge enabling network access
Dockerfile	Auxiliary	Build recipe combining Python and Node.js runtimes
Grafana	External	Target API; runs as a separate container on `hosting_web`

6. Repository Structure

_mcp-tools/
  grafana-mcp/
    Dockerfile          # Build: Python 3.12-slim + Node 20 + supergateway + mcp-grafana
  docker-compose.yml    # Service definition (shared with huggingface, pubmed, mermaid MCPs)
  .env                  # Credentials: GRAFANA_URL, GRAFANA_TOKEN, HF_TOKEN, NCBI_API_KEY
  README.md             # Stack-level documentation

This is a minimal, infrastructure-only project. There is no custom application code — the mcp-grafana package is installed from PyPI at build time and the supergateway bridge is installed from npm. The entire service logic is defined by the single Dockerfile and the CMD directive.

7. Deployment & Operations

Docker Container

Property	Value
Base image	`python:3.12-slim`
Container name	`grafana-mcp`
Exposed port	8100 (SSE)
Restart policy	`unless-stopped`
Network	`hosting_web` (external)
Traefik	Disabled (`traefik.enable=false`); routed via dynamic.yml file provider
Host	`grafana-mcp.home` (LAN via Pi-hole DNS)

Environment Variables

Variable	Purpose	Source
`GRAFANA_URL`	Internal URL of the Grafana instance	`.env` (default: `http://grafana:3000`)
`GRAFANA_SERVICE_ACCOUNT_TOKEN`	Service account token with Viewer or Admin role	`.env` as `GRAFANA_TOKEN`

Build & Deploy

cd /home/rod/_rod/_mcp-tools

# Build the image
docker compose build grafana-mcp --no-cache

# Start the service
docker compose up -d grafana-mcp

# Verify health
curl -s http://grafana-mcp.home/sse

# View logs
docker logs -f grafana-mcp

CMD Entrypoint

supergateway --stdio "mcp-grafana" --port 8100

supergateway launches mcp-grafana as a child process, communicating over stdio, and exposes the MCP protocol as an SSE HTTP endpoint on port 8100.

8. Dependencies

Runtime Dependencies

Package	Source	Purpose
`mcp-grafana`	PyPI	MCP server with Grafana tool implementations (list_dashboards, get_dashboard, query_metrics)
`supergateway`	npm	Bridges stdio-based MCP servers to SSE HTTP endpoints for network access
Python 3.12	Docker base image	Runtime for mcp-grafana
Node.js 20	NodeSource APT repo	Runtime for supergateway

Infrastructure Dependencies

Service	Relationship	Notes
Grafana	Target API	Must be running on `hosting_web` network, reachable at `grafana:3000`
Docker `hosting_web` network	Required	External network shared with hosting platform containers
Traefik	Reverse proxy	Routes `grafana-mcp.home` to container port 8100 (file provider config)
Pi-hole DNS	DNS resolution	`grafana-mcp.home` resolves to 10.0.1.6

9. Constraints & Risks

Warning

Grafana has no data sources

As of the last audit, Grafana has zero configured data sources or dashboards. The query_metrics tool will return empty results until Grafana is set up with Prometheus or another data source.

Warning

Token management

The GRAFANA_TOKEN is a service account token stored in _mcp-tools/.env. If it expires or is revoked, all MCP tool calls will fail with 401 errors.

Note

No custom code

This service has zero lines of custom application code. All logic comes from the mcp-grafana PyPI package. Upgrades are done by rebuilding the Docker image.

Note

LAN-only access

The service is only reachable on the LAN via grafana-mcp.home. There is no public-facing route through Cloudflare tunnels.

Generated by /repo-architecture v2.0.0 on 2026-03-22. This document is auto-generated — regenerate after significant changes.