Grafana Dashboards Search and Incident Investigation MCP Server

Overview

The Grafana Dashboards Search and Incident Investigation MCP Server exposes Grafana and its connected datasources through the Model Context Protocol (MCP). It lets LLM-based tools and other MCP clients search dashboards, extract dashboard and panel metadata, run queries against supported datasources (Prometheus, Loki, ClickHouse, CloudWatch, Elasticsearch), and perform targeted dashboard edits — all from the model context layer to speed troubleshooting and provide concise context to agents.

This server is useful when you want an LLM or assistant to help with incident investigation, triage, and remediation without copying entire dashboards into the model context. It provides compact summaries, JSONPath extraction to fetch only needed dashboard parts, and query execution features for metric and log inspection. Built for Grafana 9.0+, it aims to keep the context window small while giving programmatic access to the Grafana ecosystem.

Features

• Dashboard discovery and inspection
  • Search dashboards by title and metadata
  • Fetch dashboard summary (title, panel count/types, variables, metadata)
  • Get dashboard JSON by UID (warning: can be large)
  • Extract dashboard parts with JSONPath (e.g., $.panels[*].title)
  • Patch or update dashboards (full or partial updates)
  • Retrieve panel queries and associated datasource info
• Query execution and metadata
  • Run Prometheus (PromQL) instant and range queries
  • Run Loki LogQL queries and Loki metric queries
  • Execute ClickHouse SQL (with Grafana macro/variable support)
  • Query CloudWatch metrics and list namespaces/dimensions
  • Query Prometheus/Loki metadata (metric names, labels, stream stats)
• Context window management
  • get_dashboard_summary and get_dashboard_property to reduce context use
  • Patch operations for targeted changes instead of full JSON swaps
• Pluggable tools: some tools are disabled by default and can be enabled per deployment (examples, runpanelquery, clickhouse, cloudwatch)

Installation / Configuration

Minimum requirement: Grafana 9.0 or later.

Example MCP client config (for uv / uvx-based MCP clients like Claude Desktop or Cursor). Set your Grafana URL and a service account token in environment variables:

{
  "mcpServers": {
    "grafana": {
      "command": "uvx",
      "args": ["mcp-grafana"],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<YOUR_SERVICE_ACCOUNT_TOKEN>"
      }
    }
  }
}

Run the server as a local binary:

# run the server directly (assumes mcp-grafana binary on PATH)
GRAFANA_URL="https://myinstance.grafana.net" \
GRAFANA_SERVICE_ACCOUNT_TOKEN="s.xxx" \
./mcp-grafana --enabled-tools runpanelquery,examples,clickhouse

Docker example (set env vars and map ports if needed):

docker run --rm \
  -e GRAFANA_URL="http://grafana:3000" \
  -e GRAFANA_SERVICE_ACCOUNT_TOKEN="s.xxx" \
  grafana/mcp-grafana:latest

Helm / Kubernetes: deploy as a sidecar or standalone pod and pass GRAFANA_URL and token via secrets/configMaps. Expose –enabled-tools flags in container args to enable optional modules.

Enable optional tools

• Append names to the –enabled-tools flag (comma-separated). Examples:
  • runpanelquery (execute panel queries)
  • examples (query examples)
  • clickhouse
  • cloudwatch

Available Tools / Resources

Supported datasource types (capabilities depend on datasource configuration and Grafana version):

• Prometheus: queries, metadata, histogram percentiles
• Loki: log queries, metrics, patterns, metadata
• ClickHouse: table listing, schema describe, SQL queries (disabled by default)
• CloudWatch: namespaces, metrics, dimensions, queries (disabled by default)
• Elasticsearch: metadata and query support where applicable

Key endpoints / operations (overview)

Use Cases

• Incident triage: search dashboards for “HTTP 5xx” or service name, fetch panel queries, and run PromQL over the incident time window to confirm spikes.
  • Steps: search_dashboards -> get_dashboard_summary -> get_panel_queries -> query_prometheus
• Root cause exploration: extract panel query strings via get_dashboard_property ($.panels[*].targets) and run them with variable overrides to reproduce graphs.
• Log investigation: locate dashboards that reference Loki datasources, extract panel LogQL, then run targeted LogQL queries to find error traces.
• Minimal-context patches: use get_dashboard_summary and patch_dashboard to change panel thresholds or add annotations without sending the full dashboard JSON to the model.
• Data exploration: list ClickHouse tables and run ad-hoc SQL when investigating storage or query performance (enable clickhouse tool).

Practical tips

• Prefer get_dashboard_summary and get_dashboard_property when interacting with LLMs to preserve context window.
• Only enable runpanelquery, clickhouse, cloudwatch, and examples if you need those capabilities; they are disabled by default to keep the server surface minimal.
• Use a Grafana service account with least privilege required (read dashboards, run queries, and update dashboards only if needed).

GitHub: https://github.com/grafana/mcp-grafana

Tags: data-analytics, search