Grafana MCP server

The Grafana MCP Server provides tools for interacting with Grafana dashboards and data sources through the Model Context Protocol. It allows AI assistants to query metrics, logs, and dashboard information directly from Grafana instances.

Installation Options

Using UV (Recommended for Local Development)

First, set up a virtual environment and install dependencies:

uv venv .venv
source .venv/bin/activate
uv sync

Then run the server:

uv run -m src.grafana_mcp_server.mcp_server

Using Docker Compose (Recommended for Production)

1. Edit the configuration file with your Grafana details
2. Start the server:

docker compose up -d

Configuration

The server can be configured through environment variables (recommended) or a YAML file:

Environment Variables

• GRAFANA_HOST: URL of your Grafana instance
• GRAFANA_API_KEY: Your Grafana service account token
• GRAFANA_SSL_VERIFY: Set to "true" or "false" (default: "true")
• MCP_SERVER_PORT: Port for the server (default: 8000)
• MCP_SERVER_DEBUG: Enable debug logging (default: true)

Configuration File

Alternatively, create a config.yaml file:

grafana:
  host: "https://your-grafana-instance.com"
  api_key: "your-grafana-api-key-here"
  ssl_verify: "true"
server:
  port: 8000
  debug: true

Obtaining a Grafana API Key

1. Ensure you have a running Grafana instance
2. Generate a Service Account Token:
   • Navigate to Admin >> Users & Access >> Service Accounts
   • Create a Service Account with Viewer permissions
   • Generate a new Service Account token
   • Copy the token (starts with glsa_)

Integration with AI Assistants

Using Docker

Add this configuration to your AI assistant's MCP settings:

{
  "mcpServers": {
    "grafana": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "GRAFANA_HOST",
        "-e",
        "GRAFANA_API_KEY",
        "-e",
        "GRAFANA_SSL_VERIFY",
        "drdroidlab/grafana-mcp-server",
        "-t",
        "stdio"
      ],
      "env": {
        "GRAFANA_HOST": "https://your-grafana-instance.com",
        "GRAFANA_API_KEY": "your-grafana-api-key-here",
        "GRAFANA_SSL_VERIFY": "true"
      }
    }
  }
}

Connecting to a Running MCP Server

If your MCP server is already running:

{
  "mcpServers": {
    "grafana": {
      "url": "http://your-server-host:8000/mcp"
    }
  }
}

For local setups, use http://localhost:8000/mcp as the URL.

Available Tools

The MCP server provides the following tools for interacting with Grafana:

• test_connection: Verify connectivity to your Grafana instance
• grafana_promql_query: Execute PromQL queries against Prometheus datasources
• grafana_loki_query: Query Loki for log data
• grafana_get_dashboard_config: Retrieve dashboard configuration details
• grafana_query_dashboard_panels: Execute queries for specific dashboard panels
• grafana_fetch_label_values: Fetch label values for dashboard variables
• grafana_fetch_dashboard_variables: Fetch all variables from a dashboard
• grafana_fetch_all_dashboards: Fetch all dashboards with basic information
• grafana_fetch_datasources: Fetch all datasources with configuration details
• grafana_fetch_folders: Fetch all folders with metadata and permissions

Health Check

To verify the server is running:

curl http://localhost:8000/health

Troubleshooting

Common Issues

1. Connection Failed:

   • Verify your Grafana instance is accessible
   • Check API key permissions
   • Ensure SSL verification settings are correct

2. Authentication Errors:

   • Verify your API key is valid and not expired
   • Check if additional authentication is required

3. Query Failures:

   • Ensure datasource UIDs are correct
   • Verify query syntax
   • Check if datasources are accessible with your API key

Debug Mode

For more detailed logs:

export MCP_SERVER_DEBUG=true

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "grafana" '{"command":"docker","args":["run","--rm","-i","-e","GRAFANA_HOST","-e","GRAFANA_API_KEY","-e","GRAFANA_SSL_VERIFY","drdroidlab/grafana-mcp-server","-t","stdio"],"env":{"GRAFANA_HOST":"https://your-grafana-instance.com","GRAFANA_API_KEY":"your-grafana-api-key-here","GRAFANA_SSL_VERIFY":"true"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "grafana": {
            "command": "docker",
            "args": [
                "run",
                "--rm",
                "-i",
                "-e",
                "GRAFANA_HOST",
                "-e",
                "GRAFANA_API_KEY",
                "-e",
                "GRAFANA_SSL_VERIFY",
                "drdroidlab/grafana-mcp-server",
                "-t",
                "stdio"
            ],
            "env": {
                "GRAFANA_HOST": "https://your-grafana-instance.com",
                "GRAFANA_API_KEY": "your-grafana-api-key-here",
                "GRAFANA_SSL_VERIFY": "true"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "grafana": {
            "command": "docker",
            "args": [
                "run",
                "--rm",
                "-i",
                "-e",
                "GRAFANA_HOST",
                "-e",
                "GRAFANA_API_KEY",
                "-e",
                "GRAFANA_SSL_VERIFY",
                "drdroidlab/grafana-mcp-server",
                "-t",
                "stdio"
            ],
            "env": {
                "GRAFANA_HOST": "https://your-grafana-instance.com",
                "GRAFANA_API_KEY": "your-grafana-api-key-here",
                "GRAFANA_SSL_VERIFY": "true"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect