Grafana MCP Server

Implements the Model Context Protocol (MCP) specification as a Go-based server using the mark3labs/mcp-go framework, supporting three distinct transport modes: stdio for direct process integration, server-sent events (SSE) for streaming HTTP, and streamable-http for bidirectional communication. The server translates MCP client requests into Grafana API calls and datasource queries, managing protocol-level serialization, error handling, and capability advertisement through the MCP tools interface.

Enumerates all configured datasources in a Grafana instance and exposes their metadata (type, UID, URL, authentication method, capabilities) through MCP tools. The implementation queries Grafana's /api/datasources endpoint and caches results per session, enabling AI assistants to understand available data sources before constructing queries. Supports filtering by datasource type (Prometheus, Loki, Pyroscope, etc.) and exposes datasource-specific capabilities for downstream query tools.

Manages per-session configuration and multi-tenant isolation through a SessionManager that maintains separate Grafana API contexts for each MCP client session. Enables HTTP-based transports (SSE, streamable-http) to support multiple concurrent clients with different Grafana instances or organizations. Each session maintains its own authentication credentials, datasource cache, and request context, preventing cross-tenant data leakage. Supports Grafana Cloud multi-organization deployments where a single Grafana instance serves multiple organizations.

Instruments the MCP server itself with OpenTelemetry tracing and Prometheus metrics, enabling visibility into server performance, tool execution latency, and error rates. Exports traces to configured OpenTelemetry backends and Prometheus metrics on a /metrics endpoint. Tracks per-tool execution time, datasource query latency, and MCP protocol overhead. Enables operators to monitor MCP server health and identify performance bottlenecks in tool execution.

Implements MCP tool schema validation and capability advertisement through the mark3labs/mcp-go framework. Each tool is registered with a JSON Schema describing input parameters, required fields, and parameter types. The MCP server advertises available tools and their schemas to clients during initialization, enabling clients to validate inputs before execution and provide autocomplete/documentation. Validates tool inputs against schemas before execution, rejecting invalid requests with detailed error messages.

Supports Grafana dashboard variables (templating) by resolving variable values and substituting them into queries. Handles variable types (query, custom, datasource, interval) and enables queries to use variable syntax (${variable_name}). Resolves variables based on current dashboard context or explicit variable values provided by the client. Enables AI agents to execute parameterized queries using dashboard variables without manual substitution.

Respects Grafana's folder-based dashboard organization and enforces role-based access control (RBAC) at the folder level. Filters dashboard search results and panel access based on the authenticated user's folder permissions. Enables multi-team deployments where different teams have access to different folders. Integrates with Grafana's permission model to prevent unauthorized data access.

Implements comprehensive error handling for datasource failures, query timeouts, authentication errors, and malformed requests. Returns detailed error messages with diagnostic information (datasource status, query syntax errors, timeout reasons) enabling AI agents to understand failures and retry intelligently. Supports graceful degradation where partial results are returned if some datasources fail. Includes error categorization (transient vs permanent) to guide retry logic.

Executes Prometheus queries (both instant and range queries) against configured Prometheus datasources via Grafana's datasource proxy. Translates user-provided PromQL expressions into Grafana query requests, handles time range parameters (start, end, step), and returns time-series data in Prometheus native format (metric name, labels, values). Includes automatic datasource selection if multiple Prometheus sources exist, and error handling for invalid PromQL syntax or query timeouts.

Executes LogQL queries against Loki datasources to retrieve logs, perform aggregations, and extract metrics from log data. Supports both log stream queries (instant) and metric queries (range) with label filtering, regex matching, and aggregation functions (rate, count, sum, etc.). Translates user intents into LogQL syntax, handles pagination for large result sets, and returns structured log entries with timestamps and extracted fields.

Searches Grafana dashboards by title, tags, or folder and retrieves full dashboard definitions including panels, datasources, and query configurations. Uses Grafana's /api/search endpoint for discovery and /api/dashboards/uid/{uid} for full dashboard retrieval. Returns dashboard metadata (title, description, tags, folder) and optionally the complete dashboard JSON model for inspection or modification. Supports filtering by folder, starred status, and recent access.

Retrieves data for individual dashboard panels by executing the panel's configured queries and returning both the raw data and visualization metadata (panel type, axes, thresholds, legend settings). Executes panel queries through Grafana's query engine, which handles datasource routing, caching, and transformation pipelines. Returns data in the format expected by the panel's visualization type (time-series, table, stat, gauge, etc.) along with panel configuration for context.

Retrieves alert rules from Grafana Alerting (unified alerting) and their current state (firing, pending, normal). Queries alert rules by name, folder, or datasource, and returns rule definitions including conditions, thresholds, notification channels, and evaluation frequency. Provides current alert state with active instances (which labels are firing), evaluation history, and last evaluation timestamp. Supports both Grafana managed alerts and Prometheus-compatible alert rules.

Creates and retrieves annotations in Grafana, which are time-point markers used to document events, deployments, or incidents on dashboards. Supports creating annotations with tags, text, and optional dashboard/panel association. Retrieves annotations by time range, tags, or dashboard, enabling AI agents to document incident timelines or correlate events with metric changes. Annotations are stored in Grafana's annotation database and visible across dashboards.

Executes queries against Pyroscope datasources to retrieve profiling data (CPU, memory, goroutine profiles) and flame graph data. Supports querying by service name, profile type, and time range, returning profile statistics and call stack information. Integrates with Grafana's Pyroscope datasource proxy to handle authentication and data format conversion. Enables AI agents to analyze performance bottlenecks by examining profiling data alongside metrics and logs.

Integrates with Grafana OnCall (incident management platform) to create, retrieve, and manage incidents. Supports creating incidents with title, description, and severity, assigning responders, and retrieving incident details including timeline, escalation policies, and on-call schedules. Queries on-call schedules to determine who is currently on-call for a given escalation policy. Enables AI agents to automatically create incidents during alert storms or coordinate incident response.