grafana-mcp

Expose a slice of the Grafana API as an MCP (Model Context Protocol) server, focused on natural-language log querying. The main goal: say "show me error logs from the api service in the last 30 minutes" and get the actual log lines back — without juggling LogQL, labels, or datasource UIDs by hand.

Log datasources, Loki labels, and the mapping from a service name to its hosting datasource/label are cached on disk, so repeat calls skip redundant label scans.

한국어 문서 / Korean README

Installation & Setup

npx (no installation required)

Add the following to ~/.mcp.json.

{
  "mcpServers": {
    "grafana": {
      "command": "npx",
      "args": ["@seungje.jun/grafana-mcp"],
      "env": {
        "GRAFANA_URL": "https://grafana.example.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "glsa_xxx"
      }
    }
  }
}

Build from source

git clone https://github.com/ninanung/grafana-mcp.git
cd grafana-mcp
npm install
npm run build

{
  "mcpServers": {
    "grafana": {
      "command": "node",
      "args": ["/path/to/grafana-mcp/dist/cli.js"],
      "env": {
        "GRAFANA_URL": "https://grafana.example.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "glsa_xxx"
      }
    }
  }
}

Restart Claude Code to activate the MCP tools.

Authentication

One of the following is required. They are checked in the order below — the first one present wins.

All bearer-style tokens are sent as Authorization: Bearer <token>. The server does not care which kind of token it is — it only picks the one that is set.

Environment Variables

Tools

Usage Example

A typical natural-language flow, as orchestrated by the MCP client:

1. User: "Show me error logs from the api service in the last 30 minutes."

2. query_logs with service: "api", level: "error", time_from: "now-30m" → the server auto-detects which Loki datasource owns the service="api" label and runs LogQL.

3. (First call) the service → datasource/label mapping is saved to the cache; subsequent calls skip the detection step.

4. User: "Summarize those errors by pattern." → same call with output: "summarize" returns pattern-grouped counts.

5. User: "What other services do we have?" → list_services returns the full service list.

If the service name has a typo, query_logs surfaces close matches (e.g. Did you mean: checkout, checkout-api?).

How the Auto-Detection Works

query_logs picks the target datasource and label on its own:

1. Filter all datasources down to log types (Loki/ES/CloudWatch/OpenSearch/Splunk).

2. For each Loki datasource, fetch /loki/api/v1/labels and walk common service-label candidates (service, service_name, app, app_name, application, container, job) first, then any remaining labels.

3. For each candidate label, fetch its values and check whether the requested service name is in that list.

4. If exactly one (datasource, label) pair matches, use it. If multiple match, require datasource_uid to disambiguate. If none match, return close-name suggestions.

5. The resolved (service → ds_uid, label) is cached; refresh: true or refresh_log_cache forces re-detection.

Auto-detection currently supports Loki only. For Elasticsearch / CloudWatch / Splunk datasources, pass datasource_uid and service_label explicitly (and expect LogQL-specific filters not to apply).

Output Modes

query_logs accepts output:

• raw (default): <ISO timestamp> <log line> — good for direct reading in a terminal.

• summarize: groups lines by normalized pattern (numbers → N, UUIDs → UUID) with counts and a sample per pattern. Use when lines are noisy or too many.

• json: structured objects { ts, line, labels } — for downstream tooling.

Cache

• Log cache: persisted to ~/.grafana-mcp/log-cache.json. Keyed by Grafana base URL so multiple instances don't collide.

• Each category has its own TTL (datasources / labels / label values / service resolution) — see the env-var table above.

• A cached service resolution that later fails (e.g. label got renamed) is invalidated automatically so the next call re-detects.

• Use get_log_cache to inspect, refresh_log_cache to clear, and export_log_cache / import_log_cache to share with teammates.

Cache Location & Reset

The cache file is a plain JSON document — safe to inspect, edit, or back up manually.

Safety & Constraints

• Read-only: the server does not expose any endpoint that mutates Grafana state. No dashboard/datasource CRUD, no alerting changes.

• Stdio logs: all logs go to stderr, keeping the MCP stdio channel clean.

• TLS skip: GRAFANA_TLS_SKIP_VERIFY=true sets NODE_TLS_REJECT_UNAUTHORIZED=0 process-wide. Use only for self-signed Grafana in trusted networks.

• No secret logging: auth tokens are never written to audit logs.

License

MIT