Skip to main content
Glama

Grafana MCP Server

by quanticsoul4772
GitHub
TypeScript
1
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

Grafana MCP Server

A Model Context Protocol (MCP) server that provides AI-powered integration with Grafana instances. This server exposes Grafana's comprehensive functionality through standardized MCP tools, enabling programmatic interaction with dashboards, data sources, metrics, logs, alerting, and administrative functions.

Features

  • 52 MCP Tools across 8 categories for complete Grafana integration

  • Dashboard Management - Search, create, update, and analyze dashboards

  • Prometheus Integration - Execute PromQL queries and explore metrics

  • Loki Integration - Search logs with LogQL and manage log streams

  • Alerting & Incident Response - Manage alert rules and notifications

  • Administrative Tools - User, team, and organization management

  • Security-First Design - Automatic credential sanitization and error categorization

  • TypeScript Excellence - Full type safety with strict mode enabled

Installation

Prerequisites

  • Node.js 18+ with ES modules support

  • TypeScript 4.9+

  • Access to a Grafana instance (v8.0+)

Setup

# Clone the repository git clone https://github.com/your-org/grafana-mcp cd grafana-mcp # Install dependencies npm install # Build the project npm run build

Configuration

Environment Variables

Create a .env file or set these environment variables:

# Required Configuration GRAFANA_URL=https://your-grafana-instance.com GRAFANA_TOKEN=your-service-account-token-or-api-key # Optional Configuration GRAFANA_DEBUG=false # Enable debug logging GRAFANA_TIMEOUT=30000 # HTTP timeout in milliseconds GRAFANA_DISABLE_TOOLS=admin,alerting # Disable specific tool categories # TLS Configuration (Optional) GRAFANA_TLS_CERT_FILE=/path/to/client.crt GRAFANA_TLS_KEY_FILE=/path/to/client.key GRAFANA_TLS_CA_FILE=/path/to/ca.crt GRAFANA_TLS_SKIP_VERIFY=false # Skip certificate verification (insecure)

Authentication

The server supports multiple authentication methods:

  1. Service Account Tokens (Recommended)

    GRAFANA_TOKEN=glsa_xxxxxxxxxxxxxxxxxxxx

  2. API Keys (Legacy)

    GRAFANA_TOKEN=eyJrIjoi...

  3. Basic Authentication

    GRAFANA_TOKEN=admin:password

Usage

Development

# Start development server with hot reload npm run dev # Run tests npm test # Lint and format code npm run lint npm run format

Production

# Build and start production server npm run build npm start

MCP Client Integration

Configure your MCP client (e.g., Claude Desktop) to use this server:

{ "mcpServers": { "grafana": { "command": "node", "args": ["/path/to/grafana-mcp/build/main.js"], "env": { "GRAFANA_URL": "https://your-grafana.com", "GRAFANA_TOKEN": "your-service-account-token" } } } }

Available Tools

Dashboard Tools (8 tools)

  • search_dashboards - Find dashboards by title, tags, or metadata

  • get_dashboard_by_uid - Retrieve complete dashboard details

  • get_dashboard_panel_queries - Extract queries from all panels

  • update_dashboard - Create or update dashboards

  • get_dashboard_versions - View dashboard version history

  • restore_dashboard_version - Restore to a specific version

  • delete_dashboard - Remove dashboards

Prometheus Tools (6 tools)

  • query_prometheus - Execute PromQL queries

  • get_prometheus_metadata - List available metrics

  • get_prometheus_labels - Get label names

  • get_prometheus_label_values - Get values for specific labels

  • get_prometheus_series - Find time series

  • build_prometheus_query - Interactive query builder

Loki Tools (6 tools)

  • query_loki - Execute LogQL queries

  • get_loki_labels - Get log stream labels

  • get_loki_label_values - Get label values

  • get_loki_series - Find log series

  • build_logql_query - LogQL query builder

  • get_loki_stats - Ingestion statistics

Data Source Tools (4 tools)

  • list_datasources - List all configured data sources

  • get_datasource_by_uid - Get specific data source details

  • test_datasource - Test data source connectivity

  • query_datasource - Execute queries against any data source

Admin Tools (8 tools)

  • list_users - List organization users

  • get_current_user - Get current user info

  • list_teams - List teams

  • get_team_by_uid - Get team details

  • list_folders - List dashboard folders

  • get_folder_by_uid - Get folder details

  • list_api_keys - List API keys

  • list_service_accounts - List service accounts

Alerting Tools (8 tools)

  • list_alert_rules - List all alert rules

  • get_alert_rule_by_uid - Get specific alert rule

  • create_alert_rule - Create new alert rules

  • update_alert_rule - Update existing rules

  • delete_alert_rule - Delete alert rules

  • list_notification_channels - List notification channels

  • test_notification_channel - Test notification delivery

  • get_alert_history - Query alert history

Examples

Dashboard Search

// Find all dashboards tagged "monitoring" in the "Production" folder { "tool": "search_dashboards", "arguments": { "query": "error", "tags": ["monitoring"], "folder": "Production", "limit": 10 } }

Prometheus Query

// Query HTTP request rate over last 5 minutes { "tool": "query_prometheus", "arguments": { "query": "rate(http_requests_total[5m])", "datasourceUid": "prometheus-uid", "start": "2024-01-01T00:00:00Z", "end": "2024-01-01T01:00:00Z" } }

Loki Log Search

// Search for error logs in nginx service { "tool": "query_loki", "arguments": { "query": "{job=\"nginx\"} |= \"error\" | rate([5m])", "datasourceUid": "loki-uid", "limit": 100, "direction": "backward" } }

Architecture

┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ MCP Client │ │ MCP Protocol │ │ Grafana Instance│ │ (Claude AI) │◄──►│ Server │◄──►│ (REST API) │ └─────────────────┘ └─────────────────┘ └─────────────────┘

Core Components

  • MCP Server (src/main.ts) - Protocol handler and tool registry

  • HTTP Client (src/http-client.ts) - Grafana API communication

  • Services (src/services/) - Business logic for each Grafana area

  • Tools (src/tools/) - MCP tool definitions and handlers

  • Security (src/security-utils.ts) - Credential sanitization and error handling

Security Features

  • Automatic Data Sanitization - All logs and errors sanitize sensitive data

  • Error Categorization - User-safe vs internal error messaging

  • TLS Support - Full certificate validation and client certificates

  • Minimal Privilege - Tools operate with least required permissions

Deployment

Docker

FROM node:18-alpine WORKDIR /app COPY package*.json ./ RUN npm ci --only=production COPY build/ ./build/ EXPOSE 3000 CMD ["node", "build/main.js"]

Docker Compose

version: '3.8' services: grafana-mcp: build: . environment: - GRAFANA_URL=https://your-grafana.com - GRAFANA_TOKEN=${GRAFANA_TOKEN} - GRAFANA_DEBUG=false volumes: - ./logs:/app/logs

Development

Project Structure

grafana-mcp/ ├── src/ │ ├── main.ts # Entry point and MCP server setup │ ├── config.ts # Configuration management │ ├── http-client.ts # Grafana API client │ ├── security-utils.ts # Security and sanitization │ ├── error-handler.ts # Centralized error handling │ ├── tool-registry.ts # MCP tool registration │ ├── types.ts # TypeScript definitions │ ├── services/ # Business logic services │ │ ├── dashboard.ts # Dashboard operations │ │ ├── prometheus.ts # Prometheus queries │ │ ├── loki.ts # Loki log queries │ │ ├── alerting.ts # Alert management │ │ └── admin.ts # Administrative functions │ └── tools/ # MCP tool definitions │ ├── dashboard.ts # Dashboard tools │ ├── prometheus.ts # Prometheus tools │ ├── loki.ts # Loki tools │ └── admin.ts # Admin tools ├── build/ # Compiled JavaScript output ├── package.json ├── tsconfig.json ├── eslint.config.js └── README.md

NPM Scripts

{ "scripts": { "build": "tsc", // Compile TypeScript "dev": "tsx src/main.ts", // Development server "start": "node build/main.js", // Production server "test": "vitest", // Run tests "test:coverage": "vitest --coverage", // Coverage report "lint": "eslint src/", // ESLint checking "lint:fix": "eslint src/ --fix", // Auto-fix issues "format": "prettier --write src/", // Format code "type-check": "tsc --noEmit" // Type checking only } }

Code Standards

  • TypeScript Strict Mode - Full type safety enforcement

  • ESLint Rules - Zero-error policy with comprehensive rules

  • Prettier Formatting - Consistent code style

  • Zod Validation - Runtime type checking for all inputs

  • Security First - Automatic credential sanitization in all outputs

Testing

# Run all tests npm test # Run tests with coverage npm run test:coverage # Run tests in watch mode npm run test:watch # Run specific test file npm test -- dashboard.test.ts

Monitoring

Debug Mode

Enable comprehensive logging for troubleshooting:

GRAFANA_DEBUG=true npm start

Debug output includes:

  • HTTP request/response details (sanitized)

  • Tool execution traces

  • Error categorization details

  • Performance metrics

Health Checks

The server provides health information through:

  • Process exit codes

  • Error logs with categorization

  • Connection status monitoring

Contributing

We welcome contributions! Please see our contributing guidelines:

  1. Fork and Clone - Create your feature branch

  2. Code Standards - Follow TypeScript strict mode and ESLint rules

  3. Testing - Add tests for new functionality

  4. Security - Include security impact assessment

  5. Documentation - Update docs for new features

Pull Request Checklist

  • All tests pass (npm test)

  • No ESLint errors (npm run lint)

  • Code formatted (npm run format)

  • TypeScript compiles (npm run type-check)

  • Documentation updated

  • Security considerations addressed

License

[License information to be added]

Support

Common Issues

Connection Errors

Error: ECONNREFUSED - Unable to connect to Grafana

  • Verify GRAFANA_URL is correct and accessible

  • Check network connectivity and firewall rules

Authentication Failures

HTTP 401: Authentication failed

  • Verify GRAFANA_TOKEN is valid and has required permissions

  • Check token expiration and regenerate if needed

Tool Registration Errors

Schema validation failed

  • Ensure all custom tools use proper Zod schema validation

  • Check that zodToJsonSchema() wrapper is used correctly

Getting Help

Built with TypeScript, Zod, and the Model Context Protocol

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

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.

  1. Features
    1. Installation
      1. Prerequisites
      2. Setup
    2. Configuration
      1. Environment Variables
      2. Authentication
    3. Usage
      1. Development
      2. Production
      3. MCP Client Integration
    4. Available Tools
      1. Dashboard Tools (8 tools)
      2. Prometheus Tools (6 tools)
      3. Loki Tools (6 tools)
      4. Data Source Tools (4 tools)
      5. Admin Tools (8 tools)
      6. Alerting Tools (8 tools)
    5. Examples
      1. Dashboard Search
      2. Prometheus Query
      3. Loki Log Search
    6. Architecture
      1. Core Components
      2. Security Features
    7. Deployment
      1. Docker
      2. Docker Compose
    8. Development
      1. Project Structure
      2. NPM Scripts
      3. Code Standards
    9. Testing
      1. Monitoring
        1. Debug Mode
        2. Health Checks
      2. Contributing
        1. Pull Request Checklist
      3. License
        1. Support
          1. Common Issues
          2. Getting Help

        New MCP Servers

        MCP directory API

        We provide all the information about MCP servers via our MCP API.

        curl -X GET 'https://glama.ai/api/mcp/v1/servers/quanticsoul4772/grafana-mcp'

        If you have feedback or need assistance with the MCP directory API, please join our Discord server