grafana-mcp

MCP server for Grafana — manage dashboards, datasources, alert rules, folders, and annotations over stdio.

Installation

bunx @daanrongen/grafana-mcp

Tools (17 total)

| Domain | Tools | Coverage | | --------------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------- | | Dashboards | list_dashboards, get_dashboard, create_dashboard, update_dashboard, delete_dashboard | Full dashboard lifecycle | | Datasources | list_datasources, get_datasource, create_datasource, delete_datasource | Datasource management | | Alerts | list_alert_rules, get_alert_rule, list_alert_instances | Alert rules and firing Alertmanager instances | | Folders | list_folders, create_folder, delete_folder | Folder organisation | | Annotations | list_annotations, create_annotation | Dashboard and global annotations | | Health | health_check | Grafana instance status |

Configuration

| Variable | Required | Description | | ----------------- | -------- | ----------------------------------------------- | | GRAFANA_URL | Yes | Grafana base URL (e.g. http://localhost:3000) | | GRAFANA_API_KEY | Yes | Grafana service account token or API key |

Setup

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "grafana": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@daanrongen/grafana-mcp"],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_API_KEY": "your-service-account-token"
      }
    }
  }
}

Claude Code CLI

claude mcp add grafana \
  -e GRAFANA_URL=http://localhost:3000 \
  -e GRAFANA_API_KEY=your-service-account-token \
  -- bunx @daanrongen/grafana-mcp

Development

bun install
bun run dev        # run with --watch
bun test           # run test suite
bun run typecheck  # type-check with tsc
bun run lint       # biome lint
bun run format     # biome format
bun run build      # bundle to dist/main.js

Inspecting locally

Use the MCP Inspector to browse and call tools interactively against a real Grafana instance:

GRAFANA_URL=http://localhost:3000 \
GRAFANA_API_KEY=your-service-account-token \
bun run inspect

This opens the MCP Inspector UI in the browser, pointed at the locally built server.

Architecture

src/
├── config.ts                   # Effect Config — GRAFANA_URL, GRAFANA_API_KEY
├── main.ts                     # Entry point — ManagedRuntime + StdioServerTransport
├── domain/
│   ├── GrafanaClient.ts        # Context.Tag service interface (port)
│   ├── errors.ts               # GrafanaError, NotFoundError
│   ├── models.ts               # Schema.Class models (Dashboard, Datasource, AlertRule, …)
│   ├── dashboards.test.ts      # Domain tests using GrafanaClientTest
│   ├── datasources.test.ts     # Domain tests using GrafanaClientTest
│   └── health.test.ts          # Domain tests using GrafanaClientTest
├── infra/
│   ├── GrafanaClientLive.ts    # Layer using fetch against the Grafana HTTP API
│   └── GrafanaClientTest.ts    # In-memory Ref-based test adapter
└── mcp/
    ├── server.ts               # McpServer wired to ManagedRuntime
    ├── utils.ts                # formatSuccess, formatError
    └── tools/                  # dashboards.ts, datasources.ts, alerts.ts, folders.ts, annotations.ts, health.ts

License

MIT