Skip to main content
Glama
Grafana MCP Server

Grafana MCP Server

by 0xteamhq

@leval/mcp-grafana

Complete TypeScript/JavaScript implementation of the Model Context Protocol (MCP) server for Grafana, enabling AI assistants to interact with Grafana dashboards, datasources, alerts, incidents, and more.

npm version npm downloads License MCP GitHub stars

๐Ÿš€ Features

  • 43 Comprehensive Tools: Complete Grafana functionality via MCP

  • Multiple MCP Clients Support: Works with Claude Desktop, Claude Code, Cursor, Zed, Codex

  • Type-Safe Implementation: Built with TypeScript for reliability

  • Easy Installation: Available via npm/npx - no compilation needed

  • Production Ready: Comprehensive error handling and logging

  • Full Authentication Support: Service accounts, API keys, basic auth, mTLS

Related MCP server: grafana-mcp-observability

๐Ÿ“ฆ Installation

Option 1: Global Installation

npm install -g @leval/mcp-grafana

Option 2: Run with npx (no installation)

npx @leval/mcp-grafana

Option 3: Local Development

git clone https://github.com/levalhq/mcp-grafana.git
cd mcp-grafana
npm install
npm run build

๐Ÿ”ง Configuration

Environment Variables

Create a .env file in your project root:

# Required
GRAFANA_URL=https://your-grafana-instance.com

# Authentication (use one)
GRAFANA_SERVICE_ACCOUNT_TOKEN=glsa_xxxxxxxxxxxx  # Recommended
# OR
GRAFANA_USERNAME=username                        # Basic auth
GRAFANA_PASSWORD=password

# Optional
DEBUG=true                                       # Enable debug logging
TLS_CERT_FILE=/path/to/cert.pem                # mTLS certificate
TLS_KEY_FILE=/path/to/key.pem                  # mTLS key
TLS_CA_FILE=/path/to/ca.pem                    # Custom CA certificate
TLS_SKIP_VERIFY=true                            # Skip TLS verification

๐Ÿค– MCP Client Configuration

Claude Desktop

Config File Locations:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • Linux: ~/.config/Claude/claude_desktop_config.json

Configuration:

{
  "mcpServers": {
    "grafana": {
      "command": "npx",
      "args": ["@leval/mcp-grafana"],
      "env": {
        "GRAFANA_URL": "https://your-grafana.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "glsa_xxxxxxxxxxxx"
      }
    }
  }
}

Usage:

  1. Save the configuration file

  2. Restart Claude Desktop

  3. Look for the MCP icon (๐Ÿ”Œ) in the interface

  4. Ask Claude: "What dashboards are available in my Grafana?"


Claude Code (VS Code Extension)

{
  "claude.mcpServers": {
    "grafana": {
      "command": "npx",
      "args": ["@leval/mcp-grafana"],
      "env": {
        "GRAFANA_URL": "https://your-grafana.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "glsa_xxxxxxxxxxxx"
      }
    }
  }
}

Or configure globally in VS Code settings:

  1. Open Command Palette (Cmd/Ctrl + Shift + P)

  2. Search for "Preferences: Open User Settings (JSON)"

  3. Add the claude.mcpServers configuration

Usage:

  • Open Claude panel in VS Code

  • The MCP server will start automatically

  • Ask: "Show me the error rate from our Prometheus metrics"


Cursor

Configuration: Add to .cursor/settings.json in your project root:

{
  "ai.mcpServers": {
    "grafana": {
      "command": "npx",
      "args": ["@leval/mcp-grafana"],
      "env": {
        "GRAFANA_URL": "https://your-grafana.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "glsa_xxxxxxxxxxxx"
      }
    }
  }
}

Or configure globally:

  1. Open Cursor Settings (Cmd/Ctrl + ,)

  2. Go to "Features" โ†’ "AI" โ†’ "MCP Servers"

  3. Add the Grafana server configuration

Usage:

  • Press Cmd/Ctrl + K to open AI chat

  • The MCP indicator will show when connected

  • Try: "Analyze the Loki logs for errors in the last hour"


Zed

Configuration: Add to ~/.config/zed/settings.json:

{
  "assistant": {
    "version": "2",
    "mcp_servers": {
      "grafana": {
        "command": "npx",
        "args": ["@leval/mcp-grafana"],
        "env": {
          "GRAFANA_URL": "https://your-grafana.com",
          "GRAFANA_SERVICE_ACCOUNT_TOKEN": "glsa_xxxxxxxxxxxx"
        }
      }
    }
  }
}

Usage:

  1. Open Assistant panel (Cmd/Ctrl + ?)

  2. The MCP server starts automatically

  3. Ask: "List all datasources and their types"


Codex (GitHub Copilot Workspace)

Configuration: Add to .github/codex/mcp-config.json:

{
  "servers": {
    "grafana": {
      "command": "npx",
      "args": ["@leval/mcp-grafana"],
      "env": {
        "GRAFANA_URL": "https://your-grafana.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "glsa_xxxxxxxxxxxx"
      }
    }
  }
}

Usage:

  • Open Codex workspace

  • The MCP server connects automatically

  • Use in prompts: "Create a dashboard based on our current metrics"


Continue.dev

Configuration: Add to ~/.continue/config.json:

{
  "models": [...],
  "mcpServers": {
    "grafana": {
      "command": "npx",
      "args": ["@leval/mcp-grafana"],
      "env": {
        "GRAFANA_URL": "https://your-grafana.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "glsa_xxxxxxxxxxxx"
      }
    }
  }
}

Usage:

  • Open Continue panel in your IDE

  • MCP connection status shown in status bar

  • Ask: "What alerts are currently firing?"


Windsurf

Configuration: Add to .windsurf/mcp-servers.json:

{
  "grafana": {
    "command": "npx",
    "args": ["@leval/mcp-grafana"],
    "env": {
      "GRAFANA_URL": "https://your-grafana.com",
      "GRAFANA_SERVICE_ACCOUNT_TOKEN": "glsa_xxxxxxxxxxxx"
    }
  }
}

Usage:

  • Windsurf automatically detects and connects to MCP servers

  • Use Cascade AI with Grafana context

๐Ÿ“š Available Tools (43 Total)

Dashboard Management (5 tools)

Tool

Description

Example Usage

search_dashboards

Search for dashboards

"Find dashboards with 'cpu' in the name"

get_dashboard_by_uid

Get complete dashboard JSON

"Show me the dashboard with UID abc123"

get_dashboard_summary

Get dashboard metadata

"Summarize the monitoring dashboard"

get_dashboard_property

Extract specific properties

"Get all panel titles from dashboard xyz"

update_dashboard

Create or update dashboards

"Add a new panel to track memory usage"

Data Sources (3 tools)

Tool

Description

Example Usage

list_datasources

List all datasources

"What datasources are configured?"

get_datasource_by_uid

Get datasource by UID

"Show details for datasource uid-123"

get_datasource_by_name

Get datasource by name

"Get the Prometheus datasource config"

Prometheus (5 tools)

Tool

Description

Example Usage

query_prometheus

Execute PromQL queries

"Show CPU usage for the last hour"

list_prometheus_metric_names

List available metrics

"What metrics are available?"

list_prometheus_label_names

List label names

"Show all Prometheus labels"

list_prometheus_label_values

Get label values

"What values exist for the 'env' label?"

list_prometheus_metric_metadata

Get metric metadata

"Describe the node_cpu_seconds metric"

Loki Logs (5 tools)

Tool

Description

Example Usage

query_loki_logs

Execute LogQL queries

"Show error logs from the API service"

query_loki_stats

Get log stream statistics

"How many log entries in the last day?"

list_loki_label_names

List log label names

"What labels are in our logs?"

list_loki_label_values

Get log label values

"Show all namespaces in logs"

find_error_pattern_logs

Find error patterns

"Analyze error patterns in production"

Incident Management (4 tools)

Tool

Description

Example Usage

list_incidents

List incidents

"Show all active incidents"

get_incident

Get incident details

"Details for incident INC-123"

create_incident

Create new incident

"Create a critical incident for API outage"

add_activity_to_incident

Add notes to incidents

"Add update to incident INC-123"

Additional Categories

  • Alerting (3 tools): Alert rules, contact points

  • OnCall (5 tools): Schedules, shifts, on-call users

  • Sift (4 tools): Investigations, slow request analysis

  • Pyroscope (4 tools): Profiling data, performance analysis

  • Admin (2 tools): User and team management

  • Navigation (1 tool): Generate Grafana deeplinks

  • Asserts (1 tool): Entity assertions

๐Ÿ”’ Security

  1. In Grafana UI:

    • Go to Administration โ†’ Service accounts

    • Click "Add service account"

    • Name it (e.g., "mcp-server")

    • Click "Create"

    • Click "Add service account token"

    • Generate token and copy it

  2. Required Permissions:

    • dashboards:read - View dashboards

    • datasources:read - View datasources

    • alert.rules:read - View alert rules

    • logs:read - Query Loki

    • metrics:read - Query Prometheus

    • incidents:write - Manage incidents (if needed)

Best Practices

  • Use service account tokens instead of API keys

  • Store tokens in environment variables, not in code

  • Use read-only permissions where possible

  • Enable TLS/mTLS for production environments

  • Regularly rotate tokens

๐Ÿงช Testing

Quick Test

# Test connection
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-grafana.com/api/org

# Test with the MCP server
npx @leval/mcp-grafana --debug

Run Test Suite

# Clone the repository
git clone https://github.com/levalhq/mcp-grafana.git
cd mcp-grafana

# Install dependencies
npm install

# Run tests
npm test

# Test with your Grafana instance
node test/test-connection.js
node test/test-api.js

๐Ÿ“Š Performance

  • Startup time: < 1 second

  • Tool registration: < 100ms for all 43 tools

  • Query response: 200-500ms typical

  • Memory usage: ~50MB baseline

  • Connection pooling: Reuses HTTP connections

๐Ÿ› Troubleshooting

MCP Server Not Starting

# Check if running correctly
npx @leval/mcp-grafana --debug

# Should output:
# Starting MCP Grafana server with stdio transport...
# MCP server started with stdio transport

Connection Issues

# Test your credentials
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-grafana.com/api/org

# Check response - should return org details

Client Not Detecting Server

  1. Verify configuration file location

  2. Check JSON syntax is valid

  3. Restart the client application

  4. Look for MCP indicator in UI

  5. Check client logs for errors

Common Error Messages

Error

Solution

"Authentication failed"

Check your service account token

"No datasources found"

Verify datasource permissions

"Tool not found"

Ensure all tools are enabled

"Connection timeout"

Check network and Grafana URL

"Permission denied"

Add required permissions to service account

๐Ÿ“ˆ Advanced Configuration

Disable Specific Tool Categories

npx @leval/mcp-grafana \
  --disable-incident \
  --disable-oncall \
  --disable-sift

Custom TLS Configuration

export TLS_CERT_FILE=/path/to/cert.pem
export TLS_KEY_FILE=/path/to/key.pem
export TLS_CA_FILE=/path/to/ca.pem
npx @leval/mcp-grafana

Debug Mode

npx @leval/mcp-grafana --debug
# Or
export DEBUG=true
npx @leval/mcp-grafana

๐Ÿค Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

# Fork and clone
git clone https://github.com/levalhq/mcp-grafana.git
cd mcp-grafana

# Install dependencies
npm install

# Make changes and test
npm test

# Build
npm run build

# Submit PR

Feature Status

All features from the original Go implementation have been migrated:

  • โœ… Core MCP server with stdio transport

  • โœ… Dashboard operations (search, retrieve, update, create)

  • โœ… Data source management

  • โœ… Prometheus queries and metadata

  • โœ… Loki log queries and label exploration

  • โœ… Incident management and timeline

  • โœ… Alert management and contact points

  • โœ… OnCall schedules and shifts

  • โœ… Sift investigations and analysis

  • โœ… Pyroscope profiling

  • โœ… Authentication methods (API key, service account, basic auth, mTLS)

  • โœ… TLS configuration and custom CA support

๐Ÿ“„ License

Apache-2.0 - See LICENSE file for details

๐Ÿ“ฆ NPM Package

This package is published on npm as @leval/mcp-grafana

# Install globally
npm install -g @leval/mcp-grafana

# Or use directly with npx
npx @leval/mcp-grafana

# View package info
npm info @leval/mcp-grafana

๐Ÿ†˜ Support

๐ŸŽ‰ Acknowledgments

This TypeScript implementation provides full feature parity with the original Go version, with improved npm ecosystem integration and support for all major MCP clients.

Made with โค๏ธ for the Grafana and AI community

Available Tools

43 tools
add_activity_to_incidentB

Add a note (userNote activity) to an existing incident's timeline

Inputs: body (required), incidentId (required), eventTime.

create_incidentC

Create a new Grafana incident. Requires title, severity, and room prefix

Inputs: roomPrefix (required), severity (required), title (required), attachCaption, +4 more.

fetch_pyroscope_profileC

Fetches a profile from a Pyroscope data source for a given time range

Inputs: data_source_uid (required), profile_type (required), end_rfc_3339, matchers, +2 more.

find_error_pattern_logsC

Searches Loki logs for elevated error patterns and returns the results

Inputs: labels (required), name (required), end, start.

find_slow_requestsC

Searches relevant Tempo datasources for slow requests and returns the results

Inputs: labels (required), name (required), end, start.

get_alert_rule_by_uidB

Retrieves the full configuration and detailed status of a specific Grafana alert rule

Inputs: uid (required).

get_assertionsC

Get assertion summary for a given entity with its type, name, env, site, namespace, and time range

Inputs: endTime (required), entityName (required), entityType (required), startTime (required), +3 more.

get_current_oncall_usersB

Get the list of users currently on-call for a specific Grafana OnCall schedule

Inputs: scheduleId (required).

get_dashboard_by_uidB

Retrieves the complete dashboard, including panels, variables, and settings, for a specific dashboard identified by its UID

Inputs: uid (required).

get_dashboard_panel_queriesC

Retrieve panel queries and information from a Grafana dashboard

Inputs: uid (required).

get_dashboard_propertyB

Get specific parts of a dashboard using JSONPath expressions to minimize context window usage

Inputs: jsonPath (required), uid (required).

get_dashboard_summaryB

Get a compact summary of a dashboard including title, panel count, panel types, variables, and other metadata

Inputs: uid (required).

get_datasource_by_nameB

Retrieves detailed information about a specific datasource using its name.

Inputs: name (required).

get_datasource_by_uidC

Retrieves detailed information about a specific datasource using its UID.

Inputs: uid (required).

get_incidentA

Get a single incident by ID. Returns the full incident details

Inputs: id (required).

get_oncall_shiftC

Get detailed information for a specific Grafana OnCall shift

Inputs: shiftId (required).

get_sift_analysisC

Retrieves a specific analysis from an investigation by its UUID

Inputs: analysisId (required), investigationId (required).

get_sift_investigationC

Retrieves an existing Sift investigation by its UUID

Inputs: id (required).

list_alert_rulesB

Lists Grafana alert rules, returning a summary including UID, title, current state, and labels

Inputs: label_selectors, limit, page.

list_contact_pointsB

Lists Grafana notification contact points, returning a summary including UID, name, and type

Inputs: limit, name.

list_datasourcesB

List available Grafana datasources. Optionally filter by datasource type.

Inputs: type.

list_incidentsB

List Grafana incidents. Allows filtering by status and optionally including drill incidents

Inputs: drill, limit, status.

list_loki_label_namesA

Lists all available label names (keys) found in logs within a specified Loki datasource and time range

Inputs: datasourceUid (required), endRfc3339, startRfc3339.

list_loki_label_valuesB

Retrieves all unique values associated with a specific labelName within a Loki datasource and time range

Inputs: datasourceUid (required), labelName (required), endRfc3339, startRfc3339.

list_oncall_schedulesB

List Grafana OnCall schedules, optionally filtering by team ID

Inputs: page, scheduleId, teamId.

list_oncall_teamsB

List teams configured in Grafana OnCall

Inputs: page.

list_oncall_usersB

List users from Grafana OnCall. Can retrieve all users, a specific user, or filter by username

Inputs: page, userId, username.

list_prometheus_label_namesB

List label names in a Prometheus datasource. Allows filtering by series selectors and time range.

Inputs: datasourceUid (required), endRfc3339, limit, matches, +1 more.

list_prometheus_label_valuesB

Get the values for a specific label name in Prometheus. Allows filtering by series selectors and time range.

Inputs: datasourceUid (required), labelName (required), endRfc3339, limit, +2 more.

list_prometheus_metric_metadataC

List Prometheus metric metadata. Returns metadata about metrics currently scraped from targets.

Inputs: datasourceUid (required), limit, limitPerMetric, metric.

list_prometheus_metric_namesC

List metric names in a Prometheus datasource. Retrieves all metric names and filters them using regex.

Inputs: datasourceUid (required), limit, page, regex.

list_pyroscope_label_namesB

Lists all available label names found in profiles within a Pyroscope datasource

Inputs: data_source_uid (required), end_rfc_3339, matchers, start_rfc_3339.

list_pyroscope_label_valuesC

Lists all available label values for a particular label name in profiles

Inputs: data_source_uid (required), name (required), end_rfc_3339, matchers, +1 more.

list_pyroscope_profile_typesB

Lists all available profile types in a Pyroscope datasource

Inputs: data_source_uid (required), end_rfc_3339, start_rfc_3339.

list_sift_investigationsC

Retrieves a list of Sift investigations with an optional limit

Inputs: limit.

list_teamsC

Search for Grafana teams by a query string. Returns a list of matching teams with details

Inputs: query.

list_users_by_orgB

List users by organization. Returns a list of users with details like userid, email, role etc

Inputs: no named parameters.

query_loki_logsB

Executes a LogQL query against a Loki datasource to retrieve log entries or metric values

Inputs: datasourceUid (required), logql (required), direction, endRfc3339, +2 more.

query_loki_statsC

Retrieves statistics about log streams matching a given LogQL selector within a Loki datasource

Inputs: datasourceUid (required), logql (required), endRfc3339, startRfc3339.

query_prometheusA

Query Prometheus using a PromQL expression. Supports both instant and range queries.

Inputs: datasourceUid (required), expr (required), queryType (required), startTime (required), +2 more.

search_dashboardsB

Search for Grafana dashboards by a query string. Returns a list of matching dashboards with details like title, UID, folder, tags, and URL.

Inputs: query (required).

update_dashboardC

Create or update a dashboard using either full JSON or efficient patch operations

Inputs: dashboard, folderUid, message, operations, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelogโ€ฆ

    TDQS

    B3.2/5.0

    Scored across 43 tools

    Disambiguation4/5

    Most tools have distinct purposes targeting specific resources like dashboards, incidents, or datasources, with clear action differentiation (e.g., list_alert_rules vs. get_alert_rule_by_uid). However, some overlap exists in list operations across different data sources (e.g., list_loki_label_names and list_prometheus_label_names) which could cause minor confusion, though descriptions help clarify the datasource focus.

    Naming Consistency5/5

    Tool names follow a highly consistent verb_noun pattern throughout, such as list_alert_rules, get_dashboard_by_uid, and query_loki_logs. All tools use snake_case without deviation, making them predictable and easy to parse for agents, with verbs like 'list', 'get', 'query', and 'create' applied uniformly across resources.

    Tool Count2/5

    With 43 tools, the count is excessive for a single server, leading to potential cognitive overload and reduced usability. While Grafana's broad scope (incidents, dashboards, datasources, etc.) justifies many tools, this high number feels heavy and could overwhelm agents, suggesting the surface might benefit from consolidation or modularization.

    Completeness5/5

    The tool set provides comprehensive coverage for Grafana's domain, including CRUD operations for incidents, dashboards, and datasources, along with querying, listing, and analysis tools across Loki, Prometheus, and Pyroscope. There are no obvious gaps; agents can perform full lifecycle management and detailed investigations without dead ends.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      D
      maintenance
      Enables AI-powered integration with Grafana instances through 52 MCP tools for dashboard management, Prometheus/Loki queries, alerting, and administrative functions. Supports complete Grafana functionality including metrics exploration, log analysis, and incident response through natural language.
      80
      131 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to query Grafana dashboards, alerts, and datasources for observability insights and incident investigation.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to read Grafana dashboards, alert rules, and query datasources (Prometheus, Loki, etc.) through MCP tools, integrating Grafana monitoring into the IDE.
      2
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI assistants to query Grafana datasources (Prometheus/Loki metrics and SQL databases like ClickHouse/Postgres/MySQL) and search or inspect dashboards through natural language, using read-only access to Grafana's API.
      6
      MIT