Hub Grafana Extension

Connect Claude Code to Grafana for querying dashboards, exploring metrics, and analyzing alerting rules through the Model Context Protocol.

When to Use This MCP Server

Connect this server when you need to:

• Query Grafana dashboards and panels to retrieve visualization data and metrics while debugging application performance issues in Claude Code
• Explore Prometheus, Loki, or other data source metrics without switching to the Grafana web interface during development sessions
• Review alerting rules, silence configurations, and alert history to understand monitoring coverage for services you are modifying

Consider alternatives when:

• You need to create or edit complex Grafana dashboards with visual drag-and-drop panel layout, which requires the Grafana web UI
• Your monitoring data lives exclusively in Dynatrace, Datadog, or another platform with its own dedicated MCP server

Quick Start

Configuration

Copy
name: hub-grafana-extension
type: mcp
category: devtools

Example Connection

Copy
claude mcp:connect hub-grafana-extension

Available Tools

list-dashboards:     List all dashboards with tags, folder locations, and last modified dates
query-panel:         Execute the query behind a specific dashboard panel and return raw data
search-metrics:      Search available metrics across all configured data sources
get-alerts:          List alerting rules with current states and evaluation history
query-datasource:    Execute arbitrary queries against a specific Grafana data source

Core Concepts

Grafana MCP Integration Overview

Aspect	Details
Transport	stdio-based MCP server communicating with the Grafana HTTP API
Authentication	Grafana API key or service account token for programmatic access
Data Sources	Queries across Prometheus, Loki, InfluxDB, Elasticsearch, and 50+ sources
Dashboard Access	Read-only access to dashboard definitions, panel queries, and annotations
Alerting	Access to Grafana unified alerting rules, states, and notification history

Grafana MCP Architecture

Claude Code IDE
    |
    v
[MCP Client] --stdio--> [Grafana MCP Server]
                              |
                              v
                     [Grafana HTTP API]
                              |
                    +---------+---------+
                    |         |         |
                    v         v         v
              [Dashboards [Data      [Alert
               API]       Sources]   Rules]
                    \         |         /
                     [Grafana Instance]
                   Prometheus | Loki | More

Configuration

Parameter	Type	Default	Description
GRAFANA_URL	string	required	Grafana instance URL (e.g., https://grafana.example.com)
GRAFANA_API_KEY	string	required	Grafana API key or service account token with viewer permissions
default_datasource	string	none	Default data source UID to use when not specified in queries
query_timeout	integer	30000	Timeout in milliseconds for data source query execution
max_datapoints	integer	1000	Maximum number of data points to return from time-series queries

Best Practices

1. Use Viewer-Scoped API Keys - Create Grafana API keys with Viewer role permissions. This provides read access to dashboards, queries, and alerts without the ability to modify monitoring configurations accidentally.

2. Query Specific Panels for Focused Data - Rather than browsing full dashboards, use query-panel with a specific panel ID to get exactly the metric data you need. This is faster and returns more focused results than browsing dashboard JSON.

3. Search Metrics Before Writing Queries - Use search-metrics to discover available metric names and labels before constructing PromQL or LogQL queries. This prevents query errors from misspelled metric names or incorrect label selectors.

4. Review Alerts When Modifying Services - Before changing service code, use get-alerts to understand what monitoring exists for that service. Ensure your changes do not inadvertently trigger alerts or leave monitoring gaps.

5. Set Reasonable Query Time Ranges - Grafana data source queries can be expensive for wide time ranges. Start with short time ranges (last 1-6 hours) and expand only if needed. Wide ranges with high-resolution data can time out or return excessive data.

Common Issues

1. API Key Returns 401 Unauthorized - Verify the API key has not expired and is valid for the target Grafana instance. Service account tokens are preferred over legacy API keys for longer-lived programmatic access.

2. Data Source Query Returns Empty Results - The metric may not exist in the specified time range, or the query syntax may be incorrect for the data source type. Verify the query syntax matches the data source (PromQL for Prometheus, LogQL for Loki).

3. Dashboard Not Found - Dashboard UIDs are different from dashboard titles. Use list-dashboards to find the correct UID, or search by title to locate the dashboard before querying its panels.