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

1. Register Grafana instances

Create ~/.grafana-mcp/instances.json with one or more Grafana URL + credential pairs, named however you like. One instance is enough to start.

{
  "default": "dev",
  "instances": [
    { "name": "dev", "url": "https://grafana-dev.example.com", "service_account_token": "glsa_xxx" },
    { "name": "prod", "url": "https://grafana.example.com", "service_account_token": "glsa_xxx" }
  ]
}

chmod 600 ~/.grafana-mcp/instances.json

See Multiple Grafana instances for every field and rule.

2. Register the MCP server

No env is needed — the server reads the instances file.

Claude Code — user scope makes it available in every project (stored in ~/.claude.json):

claude mcp add grafana -s user -- npx @seungje.jun/grafana-mcp

Use -s project instead to share it through a .mcp.json at the project root.

Other MCP clients (e.g. Claude Desktop) — add this to the client's MCP config:

{
  "mcpServers": {
    "grafana": {
      "command": "npx",
      "args": ["@seungje.jun/grafana-mcp"]
    }
  }
}

Restart the client (or start a new Claude Code session) to activate the MCP tools.

Build from source

git clone https://github.com/ninanung/grafana-mcp.git
cd grafana-mcp
npm install
npm run build
claude mcp add grafana -s user -- node /path/to/grafana-mcp/dist/cli.js

For other clients, use "command": "node" and "args": ["/path/to/grafana-mcp/dist/cli.js"] in the JSON above.

Single instance via environment variables

The env-only setup still works: GRAFANA_URL + one credential variable is registered as an instance named default, and is merged with the instances file when both exist.

claude mcp add grafana -s user \
  -e GRAFANA_URL=https://grafana.example.com \
  -e GRAFANA_SERVICE_ACCOUNT_TOKEN=glsa_xxx \
  -- npx @seungje.jun/grafana-mcp

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

Multiple Grafana instances

Register as many URL + credential pairs as you need and switch between them in conversation — no MCP config edits or restarts.

{
  "default": "dev",
  "instances": [
    { "name": "dev", "url": "https://grafana-dev.example.com", "service_account_token": "glsa_xxx" },
    { "name": "prod", "url": "https://grafana.example.com", "service_account_token": "glsa_xxx" },
    { "name": "team-b", "url": "https://grafana.example.com", "api_key": "eyXxx...", "org_id": 2 }
  ]
}

• Fields per instance: url (required), one credential (service_account_token / cloud_access_policy_token / api_key / username + password), optional name, org_id, tls_skip_verify.

• Names are free-form (dev, qa, team-b, ...) and matched case-insensitively. If name is omitted, the URL hostname is used. Names must be unique.

• Default: the instance named by default, otherwise the first entry. A plain array of instances (without the wrapper object) is also accepted.

• Switching: use_instance name="prod" changes the active instance for the session; passing instance: "prod" to any tool targets it for that call only. Every Grafana tool result (including errors) is tagged with [instance: <name>] so you always know which Grafana answered.

• Hot reload: edits to the file are picked up on the next tool call. If the edited file is invalid, the previous list stays in effect and the result carries a warning. (At startup, an invalid file stops the server with the reason.)

• Sources are merged: the file, GRAFANA_INSTANCES, and GRAFANA_URL (registered as default) can be combined. At least one instance is required, otherwise the server refuses to start with setup instructions.

• The file stores credentials in plain text — restrict it with chmod 600 ~/.grafana-mcp/instances.json (the server warns if other users can read it).

Authentication

Each instance needs one credential. Use the field name in the instances file, or the environment variable for the GRAFANA_URL instance. 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

Related MCP server: Log Analyzer MCP Server

Tools

All tools except list_instances, use_instance, and get_log_cache / export_log_cache / import_log_cache accept an optional instance argument to target a registered instance for that call only.

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.

6. User: "Check the same thing on prod." → use_instance name="prod", then the same query_logs call runs against prod. "Compare with dev" can be a one-off query_logs with instance: "dev".

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. List datasources (/api/datasources, or /api/frontend/settings when the key is denied) and filter 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. A datasource whose label API fails is skipped; if nothing matches, the error names the skipped datasources.

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.

Grafana 8.x works as well: where /api/datasources/proxy/uid/{uid} does not exist (Grafana <9.0), Loki label and query requests go through /api/datasources/proxy/{id}, with the numeric id looked up from the datasource list. Run self_test to see which routes your instance uses.

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 (plus org_id when set) 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 / tls_skip_verify: true sets NODE_TLS_REJECT_UNAUTHORIZED=0 process-wide. With multiple instances, enabling it on one disables TLS verification for all of them (the server warns at startup and in list_instances). Use only for self-signed Grafana in trusted networks.

• Credentials file: instances.json holds tokens in plain text. Keep it chmod 600; the server warns when other users can read it.

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

License

MIT