mcp-grafana: An MCP Server for Seamless Grafana Integration

Introduction

The mcp-grafana repository hosts a Model Context Protocol (MCP) server specifically built for Grafana. This server acts as a bridge, providing extensive programmatic access to your Grafana instance and its entire ecosystem. It empowers developers and AI assistants to interact with Grafana's core functionalities, including dashboards, datasources, alerting, incidents, and more, enabling advanced automation, intelligent querying, and dynamic reporting.

With mcp-grafana, you can seamlessly integrate Grafana's rich observability data and management capabilities into external applications, scripts, or AI-driven workflows, enhancing operational efficiency and data-driven decision-making.

Installation

Getting started with mcp-grafana is straightforward, with several installation options available. The recommended method uses uvx for ease of deployment.

Quick Start with uvx

If you have uv installed, uvx can automatically download and run the server:

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

For Grafana Cloud, replace GRAFANA_URL with your instance URL, for example, https://myinstance.grafana.net. Ensure your Grafana service account has the necessary permissions.

Other Installation Methods

Docker Image: Use the pre-built Docker image from Docker Hub. For STDIO mode, which is common for AI assistant integration, explicitly override the default SSE mode:
```
docker run --rm -i -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> grafana/mcp-grafana -t stdio
```
Binary Download: Download the latest release from the releases page and add it to your $PATH.
Helm Chart: Deploy to Kubernetes using the Helm chart from the Grafana helm-charts repository.

Examples

mcp-grafana exposes a rich set of tools to interact with your Grafana instance. Here are some common use cases:

Dashboard Management: Search for dashboards, retrieve compact summaries, extract specific properties using JSONPath, or even update and create new dashboards. Tools like get_dashboard_summary and get_dashboard_property are crucial for efficient context window management when working with large dashboards.
Data Source Querying: Execute queries against various data sources like Prometheus, Loki, InfluxDB, ClickHouse, CloudWatch, Athena, Snowflake, and Elasticsearch/OpenSearch. This includes querying metrics, logs, metadata, and even log patterns.
Alerting and Incidents: List and manage alert rules, view notification policies, and interact with Grafana Incident to search, create, and update incidents.
OnCall Management: Integrate with Grafana OnCall to list schedules, get shift details, and identify current on-call users.
Navigation and Rendering: Generate accurate deep links to Grafana dashboards, panels, and Explore views. You can also render dashboard panels or entire dashboards as PNG images, useful for reports or automated alerts. This requires the Grafana Image Renderer service.
Admin Tasks: List teams, users, roles, and permissions within your Grafana organization.

Many advanced data source and administrative tools are disabled by default and can be enabled via CLI flags like --enabled-tools.

Why use mcp-grafana?

mcp-grafana offers significant advantages for anyone looking to extend Grafana's capabilities programmatically:

Comprehensive Grafana Access: Provides a unified interface to almost every aspect of Grafana, from data querying to administrative tasks.
AI/LLM Integration Ready: Designed with the Model Context Protocol, making it ideal for integration with AI assistants and large language models for intelligent observability.
Flexible Deployment: Supports multiple deployment strategies, including uvx, Docker, direct binary, and Helm, fitting various operational environments.
Granular Control: Offers extensive configuration options, including tool enablement/disablement and fine-grained RBAC permissions, allowing you to tailor access and functionality to your specific needs.
Observability Built-in: Includes Prometheus metrics, OpenTelemetry tracing, and structured log export, ensuring that the server itself is observable and easy to monitor.
Read-Only Mode: A dedicated --disable-write flag provides a secure read-only mode, perfect for AI assistants or environments where data modification should be restricted.