Grafana MCP

This project provides MCP server for Grafana, including MCP tools to interact with Grafana dashboards, data sources, alerts, and more.

The package includes a dashboard template resource that is properly bundled with the package for use when installed.

Usage

Installation

1. Create a virtual environment (recommended)

python -m venv venv
source venv/bin/activate

2. Install this package directly from GitHub using pip:

pip install -e git+https://github.com/izaitsevfb/grafana-mcp.git#egg=grafana_mcp

(Alternatively, you can install it locally with pip install -e .)

3. Configure Grafana authentication

Create a .env file with your Grafana URL and API token:

cp .env.example .env

Then edit the .env file to add your actual Grafana URL and API token:

GRAFANA_URL=http://your-grafana-server:3000
GRAFANA_API_TOKEN=your-api-token-here

You can generate an API token in Grafana by navigating to: Configuration → API Keys → New API key.

4. After installation, the MCP server can be run as:

python -m grafana_mcp

5. Add this MCP server to Claude Code:

claude mcp add-json grafana '{ "type": "stdio", "command": "python", "args": [ "-m", "grafana_mcp" ], "env": {} }'

Note: By default, MCP config applies only to the current directory. If you want to use it globally, add --scope user to the command above:

claude mcp add-json --scope user grafana '{ "type": "stdio", "command": "python", "args": [ "-m", "grafana_mcp" ], "env": {} }'

6. Run Claude Code as usual:

claude

Development

Development Installation

1. Clone the repository
2. Install in development mode:

   pip install -e .
   

The package uses Python's package resource management system to include the dashboard template. The dashboard.json file is stored in the src/grafana_mcp/ directory and is accessed using importlib.resources when the package is installed.

Testing

Run unit tests:

python -m unittest discover tests

For testing with token authentication, ensure you have created a .env file with your Grafana credentials as described above. The test suite includes mocked tests that don't require an actual Grafana instance.

Tools

The Grafana MCP provides the following tools:

Available Tools

Dashboard Management

• get_grafana_info(): Get information about the connected Grafana instance including version and connection status
• list_dashboards(): List all dashboards from the connected Grafana instance
• get_dashboard(uid): Get details about a specific dashboard by UID

Organization Management

• get_organization(): Get information about the current organization

Data Source Management

• list_datasources(): List all available data sources

Requirements

• grafana-client: Python client for Grafana API
• python-dotenv: For loading environment variables from .env file
• mcp: Model Context Protocol server implementation

Authentication

This package uses token authentication with the Grafana API. To configure authentication:

1. In your Grafana instance, create an API key with appropriate permissions
2. Create a .env file with the following variables:

   GRAFANA_URL=http://your-grafana-url:3000
   GRAFANA_API_TOKEN=your-api-token-here
   

3. The MCP server will automatically load these credentials when started

More tools and features will be added in future versions.