mcp-grafana

0.14.0 verified Sat May 09 auth: no python

MCP server for Grafana – enables AI agents to interact with Grafana via the Model Context Protocol. Current version: 0.14.0. Released roughly monthly by Grafana Labs.

pip install mcp-grafana

Common errors

error ModuleNotFoundError: No module named 'mcp_grafana' ↓

cause mcp-grafana is not installed or installed in wrong environment.

fix

Run 'pip install mcp-grafana' in the target Python environment.

error Error: GRAFANA_URL not set ↓

cause Environment variable GRAFANA_URL is missing.

fix

Set GRAFANA_URL before running (e.g., export GRAFANA_URL='http://localhost:3000').

error 401 Unauthorized ↓

cause Missing or invalid GRAFANA_API_KEY or service account token.

fix

Ensure GRAFANA_API_KEY is set with a valid Grafana API key. For service account, use SA token directly.

Warnings

breaking In v0.13.0 the `search_logs` tool was removed. Tools that relied on it will fail. ↓

fix Use `search_logs` substitute if available, or query logs via `generic_request` tool added in v0.14.0.

gotcha The `GRAFANA_URL` must not have a trailing slash; mcp-grafana trim logic may cause double slashes in paths. ↓

fix Set GRAFANA_URL without trailing slash (e.g., http://localhost:3000).

gotcha OpenTelemetry OTLP trace and log export is enabled only when environment variables `OTEL_EXPORTER_OTLP_ENDPOINT` or `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` are set. No telemetry by default. ↓

fix Set the environment variables to enable OTLP export.

Imports

Server
wrong
```
from mcp_grafana import Server
```
correct
```
from mcp import Server
```
mcp-grafana does not re-export MCP Server; import from mcp directly.
main
```
from mcp_grafana import main
```
Entry point typically called via CLI, but main() can be imported programmatically.

Quickstart

Run the Grafana MCP server. Requires GRAFANA_URL and GRAFANA_API_KEY environment variables.

import os
from mcp_grafana import main

# Set environment variables for authentication
os.environ['GRAFANA_URL'] = os.environ.get('GRAFANA_URL', 'http://localhost:3000')
os.environ['GRAFANA_API_KEY'] = os.environ.get('GRAFANA_API_KEY', '')

# Run the MCP server
if os.environ['GRAFANA_API_KEY']:
    main()
else:
    print('Set GRAFANA_API_KEY environment variable')