Grafana MCP Server Project Details

Project Overview

Grafana MCP Server is a server based on the Model Context Protocol (MCP), specifically designed for integration with Grafana instances and their surrounding ecosystem. This project provides AI agents (such as Claude Desktop) with the ability to access and manipulate various Grafana functionalities.

Core Features

Dashboard Management

• Search Dashboards: Quickly retrieve and locate specific dashboards.
• Get Dashboard: Obtain the complete dashboard configuration by UID.
• Update/Create Dashboard: Dynamically modify or create new dashboards (note context window limitations).

Data Source Integration

• Data Source Management: List and retrieve data source information.
• Multi-Data Source Query Support:
  • Prometheus: Execute PromQL queries to obtain metric data.
  • Loki: Execute LogQL queries to retrieve log data.
  • Tempo: Distributed tracing data query.
  • Pyroscope: Performance profiling data query.

Metadata Query

• Prometheus Metadata: Obtain metric metadata, metric names, label names, and label values.
• Loki Metadata: Obtain log label names, label values, and statistics.

Event and Alert Management

• Event Management: Search, create, update, and close events.
• Alert Rules: List and retrieve alert rule information, and get alert status.
• Contact Points: List, create, and modify alert contact points.

Grafana OnCall Integration

• Schedule Management: List and manage on-call schedules.
• On-Call Information: Obtain on-call details and the current on-call user.
• Team and User Management: Manage teams and user information.
• Alert Group Management: List alert groups.

Sift Investigation Features

• Smart Investigation: Initiate Sift investigations and view results.
• Investigation Management: Create, list, and retrieve investigation information.
• Analysis Features: Obtain investigation analysis results.
• Error Pattern Recognition: Find error patterns in logs.
• Performance Analysis: Identify slow requests.

Tool Configuration

This project provides flexible tool configuration options, allowing you to enable or disable specific feature categories:

Tool Name	Category	Description
search_dashboards	Search	Search dashboards
get_dashboard_by_uid	Dashboard	Get dashboard by UID
update_dashboard	Dashboard	Update or create new dashboard
list_datasources	Datasources	List data sources
query_prometheus	Prometheus	Execute Prometheus query
query_loki_logs	Loki	Query and retrieve logs
list_incidents	Incident	List incidents
list_alert_rules	Alerting	List alert rules
list_oncall_schedules	OnCall	List OnCall schedules
find_error_pattern_logs	Sift	Find error patterns

Use the --disable-<category> flag to disable specific tool categories. For example, use --disable-oncall to disable OnCall-related tools.

Installation and Configuration

Installation Methods

1. Docker Image

docker pull mcp/grafana
docker run -p 8000:8000 -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_API_KEY=<your_token> mcp/grafana

2. Download Binary File

Download the latest version from the releases page and place it in the $PATH directory.

3. Compile from Source

GOBIN="$HOME/go/bin" go install github.com/grafana/mcp-grafana/cmd/mcp-grafana@latest

Configuration Settings

Prerequisites

1. Create a service account in Grafana and assign sufficient permissions.
2. Generate a service account token.

Claude Desktop Configuration

Using Binary File:

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

Using Docker:

{
  "mcpServers": {
    "grafana": {
      "command": "docker",
      "args": [
        "run", "--rm", "-p", "8000:8000",
        "-e", "GRAFANA_URL", "-e", "GRAFANA_API_KEY",
        "mcp/grafana"
      ],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_API_KEY": "<your service account token>"
      }
    }
  }
}

Debug Mode

Enable debug mode by adding the -debug flag to provide detailed HTTP request and response logs:

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

Development and Testing

Development Environment Setup

# Run the server
make run

# Build Docker image
make build-image

# Run Docker container
docker run -it --rm -p 8000:8000 mcp-grafana:latest

Test Types

Unit Tests

make test-unit
# Or
make test

Integration Tests

# Requires a running Docker container
make test-integration

Cloud Tests

# Requires a cloud Grafana instance and credentials
make test-cloud

Full Tests

# Start a local Grafana instance
docker-compose up -d

# Run all tests
make test-all

Code Quality

Code Linting

make lint

JSON Schema Check

The project includes a custom linter to check for unescaped commas in jsonschema struct tags:

make lint-jsonschema

Technical Architecture

• Programming Language: Go
• Protocol: Model Context Protocol (MCP)
• Communication Method: stdin/stdout or SSE (Server-Sent Events)
• Supported Clients: MCP-compatible clients such as Claude Desktop

Use Cases

1. AI-Driven Monitoring: Enable AI agents to intelligently query and analyze monitoring data.
2. Automated Operations: Automatically create and manage dashboards and alert rules through AI.
3. Intelligent Incident Response: Utilize AI to analyze logs and metrics, quickly locate and resolve issues.
4. Data Insights: Allow AI to help extract valuable information from complex monitoring data.

This project represents a new trend in the integration of AI with traditional monitoring tools, providing developers with a powerful bridge connecting AI assistants and the Grafana ecosystem.