Grafana Server MCP
Read-only access to Grafana environments: lists configured environments and their Prometheus/Loki datasources, then runs PromQL metric queries (instant or range), LogQL log queries with limits, and LogQL metric queries, plus metric/label discovery — with compacted, size-capped results and tokens scrubbed.
Queries Prometheus metrics through a Grafana datasource: list metric names (optionally filtered), list label names or the values of a single label, and evaluate PromQL queries as instant or range (via since or from/to).
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Grafana Server MCP
Read-only FastMCP server for Grafana metrics (Prometheus) and logs (Loki). It wraps the
gcx CLI, supports several Grafana environments at once
(e.g. dev, stg-west, prod) and runs as a localhost-only Docker/Podman compose service.
Only an allowlist of read-only gcx subcommands is ever executed; there are no write tools.
Tools
Every tool except list_environments takes a required env (one of the names returned by
list_environments); there is no default environment. datasource is a UID or exact name
and may be omitted when the environment has exactly one datasource of the needed type.
Tool | Description |
| Configured environments (name, url, org_id). Never returns tokens. |
| Prometheus and Loki datasources of an environment (uid, name, type, isDefault). |
| Prometheus metric names, optionally filtered. |
| Prometheus label names, or the values of one label. |
| PromQL query: instant by default, range with |
| Loki label names, or the values of one label. |
| LogQL log query, newest first ( |
| LogQL metric query (e.g. |
Results are compacted and capped (50 000 characters by default) and say when they were truncated. gcx errors are returned as tool errors with any token scrubbed.
Related MCP server: tiny-loki-mcp
Quickstart
Prerequisites: Docker or Podman with compose, uv, and a working host gcx configuration
(one gcx context per Grafana environment, authenticated with a service-account token).
# 1. Export your gcx contexts and keyring tokens to grafana.env (mode 0600, gitignored)
make env # all contexts
make env ARGS="--contexts dev,prod --force" # a subset / update an existing grafana.env
# 2. Build and start the container (published on 127.0.0.1:8004)
docker compose up -d --build # or: make up (Podman: see below)
# 3. Register it with Claude Code
claude mcp add --transport http grafana http://127.0.0.1:8004/mcp
# ...or with GitHub Copilot CLI (then check with `copilot mcp list`)
copilot mcp add --transport http --timeout 120000 grafana http://127.0.0.1:8004/mcpmcp_config_http.json is an equivalent client configuration for other MCP clients.
If host port 8004 is already taken, set GRAFANA_MCP_PORT in .env (read by compose for
interpolation, not passed to the container) and use that port in the client URL.
Alternatively, copy grafana.env.example to grafana.env, chmod 600 grafana.env and fill
it in by hand. The file and service names match a multi-server compose stack, so
grafana.env can be copied there as is.
With GRAFANA_LOG_PATH set (the compose default), structured tool logs go to
/var/log/grafana-mcp/server.log in the grafana_logs volume, not to make logs. Read them with:
docker compose exec grafana-mcp-1 tail -f /var/log/grafana-mcp/server.logOther targets: make down, make logs, make docker-build, make check (ruff + mypy + pytest).
Configuration
Environments are declared by name; each name maps to a variable prefix: the name uppercased
with every non-alphanumeric character replaced by _ (stg-west → GRAFANA_STG_WEST_*).
Variable | Required | Description |
| Yes | Comma-separated environment names, e.g. |
| Yes | Grafana base URL, e.g. |
| Yes | Service-account token ( |
| No | Grafana organisation id (default |
| No | Per-call gcx timeout in seconds (default |
| No | Max concurrent gcx processes (default |
| No | Result size cap (default |
| No | gcx binary (default |
| No | Structured JSON log file (set by compose to a volume) |
| No | Host port for compose (default |
| No | Passed through to gcx |
| No | Host path of an extra PEM CA bundle (compose mounts it) |
| No |
|
| No | HTTP bind address (image: |
Friendly environment names
The environment names are whatever your gcx contexts are called. If you prefer to talk about
"staging" or "the EU cluster", map those words to environment names in your own Claude skill
or CLAUDE.md (kept outside this repository) rather than renaming contexts.
Local development (without a container)
uv venv .venv && uv pip install -e ".[dev]"
source .venv/bin/activate
make check
make run-stdio # or: make run-http (127.0.0.1:8000)This uses the gcx on your PATH and the same GRAFANA_* variables (read from grafana.env, or .env).
Security
Localhost only. The MCP endpoint has no authentication. Compose publishes it on
127.0.0.1only; do not publish the port beyond localhost.Read-only. Only allowlisted read-only gcx subcommands can run. Still, use Viewer-role service-account tokens so the credentials themselves cannot write.
Tokens.
grafana.envis written with mode0600and is gitignored and excluded from the image build context. Inside the container the tokens live in the environment and in a gcx config on a tmpfs; anyone who can rundocker inspecton your host can read them. This is acceptable for a single-user workstation, not for a shared host.Tokens are never logged or returned by tools; gcx output is scrubbed of them.
Troubleshooting
Works with gcx on the host, but tools fail in the container (timeouts, DNS or TLS errors):
VPN with an HTTP proxy: set
HTTPS_PROXY(andNO_PROXY) ingrafana.env; they are passed to gcx.TLS-intercepting proxy: set
GRAFANA_EXTRA_CA_FILE=/path/to/ca.pemin.env. The entrypoint appends it to a copy of the system CA bundle and setsSSL_CERT_FILE.Last resort, host networking: use the commented
network_mode: hostblock indocker-compose.yml. Port publishing does not apply then, so removeports:and keepMCP_HTTP_HOST=127.0.0.1so the server binds to localhost itself.
Zero-trust clients such as Zscaler Private Access usually work from a container on the default network without any of the above. The proxy path is best-effort and less tested.
Container unhealthy / not starting: make logs. A configuration error (e.g. a missing
GRAFANA_<PREFIX>_TOKEN) is reported at startup with the variable name, never its value.
Podman
Rootless Podman works as docker: the Dockerfile uses fully qualified image names
(docker.io/library/python:3.12-slim) and the healthcheck uses Python rather than curl.
docker compose / podman compose with docker-compose as the provider works out of the
box; a bare docker-compose (v1) needs DOCKER_HOST=unix://$XDG_RUNTIME_DIR/podman/podman.sock.
The healthcheck is a single CMD-SHELL string because Podman splits exec-form arguments on
spaces. In host-network mode the port is the one the server binds (MCP_HTTP_PORT).
Image
Multi-stage build on python:3.12-slim, runs as the non-root mcp user. gcx is downloaded
from the official grafana/gcx GitHub release (--build-arg GCX_VERSION=1.7.1) and verified
against the release's checksums.txt. The image contains no configuration and no secrets.
License
MIT
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Read-only access to a Lumin project's logs, metrics, uptime checks, alerts and infrastructure.
Lets AI agents analyze API metrics, request logs, and traces, and manage apps and alerts.
Provides read access to your GKE and Kubernetes resources.
Query Honeycomb observability data: traces, events, metrics, SLOs, triggers, and boards.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides read-only access to Loki, Prometheus, and Tempo APIs, enabling natural language queries for logs, metrics, and traces. Supports multiple instances and authentication via bearer tokens.1MIT
- AlicenseAqualityCmaintenanceEnables read-only querying of Grafana Loki logs through tools like label discovery, LogQL queries, and recent log retrieval, without requiring knowledge of the Loki API.4MIT
- AlicenseNot gradedqualityBmaintenanceGives AI coding agents read-only access to Grafana's Loki logs, Prometheus metrics, Tempo traces and active alerts from within a project, using per-project context declared in the repo and one-command switching between test and prod environments. Credentials are discovered by parsing shell rc files directly, so it works even when spawned as a non-interactive MCP client process.80 npm1MIT
- AlicenseAqualityBmaintenanceEnables agents to explore dashboards and run their panel queries with template variables resolved, query Prometheus and Loki datasources, and read alerts, silences and annotations across Grafana's sources in a context-friendly, read-only-by-default form, with write tools available only when explicitly enabled.1440 npmMIT