MCP Read-Only Grafana Server

A secure MCP (Model Context Protocol) server for Grafana with a read-only default and a separate mcp-grafana-write command for write-capable workflows.

Default layout:

• Live config: ~/.config/lukleh/mcp-read-only-grafana/connections.yaml
• Credentials: injected via the MCP client or shell environment
• Rotated session state: ~/.local/state/lukleh/mcp-read-only-grafana/session_tokens.json
• Cache: ~/.cache/lukleh/mcp-read-only-grafana/

Compatibility: Targeted and tested against Grafana 9.5.x. Newer versions (e.g., 10.x) should work for read-only endpoints but may expose extra fields not covered here.

Features

• Read-only by default - mcp-read-only-grafana exposes the safe default surface
• Separate write command - mcp-grafana-write enables dashboard saves, alerting writes, folders, and related mutations from the same package
• API key first authentication - Prefers Grafana API keys or service-account tokens for stable machine access
• Deprecated session-cookie fallback - Still supports Grafana session cookies, including automatic capture of rotated cookies in session_tokens.json
• Hierarchical dashboard navigation - Handle large dashboards efficiently with lightweight metadata queries and per-panel detail fetching
• Multiple instances - Support for multiple Grafana connections
• Comprehensive API coverage - Access dashboards, panels, folders, datasources, and alerts
• Security focused - Timeouts, SSL verification, and secure token storage

Prerequisites

• Python 3.11 or higher
• uv
• Grafana credentials for at least one instance
• an MCP client such as Claude Code or Codex

Quick Start

1. Install the Server

# Run the published package without cloning the repository
uvx mcp-read-only-grafana@latest --write-sample-config

# Or install it once and reuse the command directly
uv tool install mcp-read-only-grafana
mcp-read-only-grafana --write-sample-config

# The same install also provides the separate write-capable command
mcp-grafana-write --print-paths

When using uvx, prefer mcp-read-only-grafana@latest in user-facing docs and MCP client configs. This avoids reusing a stale cached tool environment after a new release is published. For the separate write-capable command, use uvx --from mcp-read-only-grafana@latest mcp-grafana-write.

The command above writes a starter config and matching schema to:

• ~/.config/lukleh/mcp-read-only-grafana/connections.yaml
• ~/.config/lukleh/mcp-read-only-grafana/connections.schema.json

The live runtime config file used by the installed server is ~/.config/lukleh/mcp-read-only-grafana/connections.yaml.

2. Confirm Runtime Paths

uvx mcp-read-only-grafana@latest --print-paths

Where connections.yaml Lives

By default, the server reads the live runtime config from:

• ~/.config/lukleh/mcp-read-only-grafana/connections.yaml

On this machine, that expands to:

• /Users/<your-user>/.config/lukleh/mcp-read-only-grafana/connections.yaml

Important distinction:

• The live runtime file is ~/.config/lukleh/mcp-read-only-grafana/connections.yaml
• The checked-in repo sample is connections.yaml.sample

The sample file documents the format, but it is not the file the installed server reads unless you explicitly copy or generate it into the runtime config directory.

3. Edit the Connections File

Edit ~/.config/lukleh/mcp-read-only-grafana/connections.yaml with your Grafana instances:

- connection_name: production_grafana
  url: https://grafana.example.com
  description: Production Grafana instance
  api_key: glsa…[redacted]

- connection_name: staging_grafana
  url: https://staging-grafana.example.com
  description: Staging Grafana instance

4. Set Up Authentication

You can keep credentials either directly in connections.yaml or in the environment used to launch the server. Prefer api_key for normal use. For local shell testing you can export credentials directly; for normal MCP use, inject them through the client config when you want runtime overrides.

YAML credentials:

- connection_name: production_grafana
  url: https://grafana.example.com
  api_key: glsa…[redacted]

You can authenticate with either a Grafana API key or a deprecated session cookie fallback:

• API key or service-account token:

  export GRAFANA_API_KEY_PRODUCTION_GRAFANA=your_api_key_here
  

• Deprecated session cookie fallback:

  export GRAFANA_SESSION_PRODUCTION_GRAFANA=your_session_token_here
  

Precedence is:

• Rotated session cookies in session_tokens.json
• Runtime environment variables
• Credentials declared in connections.yaml

If both a session token and an API key are available for the same connection, the server prefers the API key.

Deprecated: How to Get a Grafana Session Token

1. Log in to Grafana in a web browser
2. Open developer tools
3. Go to Application/Storage -> Cookies
4. Find the cookie named grafana_session or grafana_sess
5. Copy the value and export or inject it as GRAFANA_SESSION_<CONNECTION_NAME>

Use this only as a temporary fallback. Browser session cookies rotate and expire quickly, so they are less reliable than API keys for MCP usage.

How to Get a Grafana API Key

1. In Grafana, go to Administration -> Service Accounts or Configuration -> API Keys
2. Create a key with the minimum required permissions
3. Export or inject it as GRAFANA_API_KEY_<CONNECTION_NAME>

If you start with a session cookie, the server will keep refreshed cookies in ~/.local/state/lukleh/mcp-read-only-grafana/session_tokens.json. On later requests, that persisted state file takes precedence over the live GRAFANA_SESSION_* environment value and any static session_token in connections.yaml until you update or remove it.

5. Configure Your MCP Client

Claude Code

claude mcp add mcp-read-only-grafana \
  --scope user \
  -e GRAFANA_API_KEY_PRODUCTION_GRAFANA=your_api_key_here \
  -- uvx mcp-read-only-grafana@latest

Codex

codex mcp add mcp-read-only-grafana \
  --env GRAFANA_API_KEY_PRODUCTION_GRAFANA=your_api_key_here \
  -- uvx mcp-read-only-grafana@latest

If you absolutely need the deprecated session-cookie fallback, swap GRAFANA_API_KEY_* for GRAFANA_SESSION_* in the MCP client config.

If you want the write-capable endpoints, launch the separate write command from the same package:

uvx --from mcp-read-only-grafana@latest mcp-grafana-write

For a persistent install created with uv tool install mcp-read-only-grafana, run mcp-grafana-write directly.

6. Restart and Test

Restart your MCP client and try a simple query such as:

List all dashboards in the production Grafana instance.

Command Line Testing

# Show the resolved runtime paths
uvx mcp-read-only-grafana@latest --print-paths

# Write or refresh the default connections.yaml
uvx mcp-read-only-grafana@latest --write-sample-config
uvx mcp-read-only-grafana@latest --write-sample-config --overwrite

# Run the server with the default home-directory config
uvx mcp-read-only-grafana@latest

# Run the separate write-capable command from the same package
uvx --from mcp-read-only-grafana@latest mcp-grafana-write

# Point the server at a different config root
uvx mcp-read-only-grafana@latest --config-dir /path/to/config-dir

# Validate the generated configuration
uvx mcp-read-only-grafana@latest validate-config

# Test all configured Grafana connections
uvx mcp-read-only-grafana@latest test-connection

# Test one specific connection
uvx mcp-read-only-grafana@latest test-connection production_grafana

Local Development

If you want to work on the repository itself:

git clone https://github.com/lukleh/mcp-read-only-grafana.git
cd mcp-read-only-grafana
uv sync --extra dev
uv run pytest -q
uv run mcp-read-only-grafana --print-paths
uv run mcp-grafana-write --print-paths

The checked-in sample file remains available at connections.yaml.sample for documentation and review, but package users should prefer --write-sample-config.

Even during local development, the server still uses the resolved runtime config path by default. It does not automatically read the repo's connections.yaml.sample.

Available MCP Tools

list_connections

List all configured Grafana instances.

Returns: JSON with connection names, URLs, and descriptions

get_health

Check Grafana instance health and version.

Parameters:

• connection_name (required): Name of the Grafana connection

Returns: Health status and version information

search_dashboards

Search for dashboards by name or tag.

Parameters:

• connection_name (required): Name of the Grafana connection
• query (optional): Search query for dashboard names
• tag (optional): Tag to filter dashboards
• limit (optional): Maximum results per page (Grafana default 1000, max 5000)
• page (optional): Page number (1-indexed)
• fields (optional): Subset of Grafana fields to return (e.g., uid, title, url, type, tags, folderTitle, folderUid)

Returns: List of matching dashboards with UIDs, titles, and tags

get_dashboard_info

Get lightweight dashboard metadata and panel list (without full panel definitions). Recommended first step for exploring dashboards, especially large ones.

Parameters:

• connection_name (required): Name of the Grafana connection
• dashboard_uid (required): UID of the dashboard

Returns: Dashboard metadata, variables, and list of all panels with basic info

get_dashboard_panel

Get full configuration for a single panel from a dashboard. Use this after get_dashboard_info() to explore specific panels in detail.

Parameters:

• connection_name (required): Name of the Grafana connection
• dashboard_uid (required): UID of the dashboard
• panel_id (required): Panel ID to retrieve

Returns: Full panel JSON including queries, transformations, and field config

get_dashboard

Get complete dashboard definition. Use with caution for large dashboards - may exceed token limits. Prefer get_dashboard_info() + get_dashboard_panel() for large dashboards.

Parameters:

• connection_name (required): Name of the Grafana connection
• dashboard_uid (required): UID of the dashboard

Returns: Full dashboard JSON including panels, variables, and settings

get_dashboard_panels

Get simplified panel information from a dashboard. Returns basic panel metadata without full configuration.

Parameters:

• connection_name (required): Name of the Grafana connection
• dashboard_uid (required): UID of the dashboard

Returns: List of panels with IDs, titles, types, and descriptions

list_folders

List all folders in Grafana.

Parameters:

• connection_name (required): Name of the Grafana connection

Returns: Folder hierarchy with IDs and titles

list_folder_dashboards

List all dashboards within a specific folder.

Parameters:

• connection_name (required): Name of the Grafana connection
• folder_uid (required): UID of the folder
• limit (optional): Maximum results per page
• page (optional): Page number
• fields (optional): Subset of Grafana fields (e.g., uid, title, url, tags, folderUid)

Returns: List of dashboards in the folder with UIDs, titles, and URLs

list_datasources

List configured data sources.

Parameters:

• connection_name (required): Name of the Grafana connection

Returns: Data source names, types, UIDs, and configuration

`ge