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:

Service Account Tokens (Recommended)
GRAFANA_TOKEN=glsa_xxxxxxxxxxxxxxxxxxxx
API Keys (Legacy)
GRAFANA_TOKEN=eyJrIjoi...
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:

Fork and Clone - Create your feature branch
Code Standards - Follow TypeScript strict mode and ESLint rules
Testing - Add tests for new functionality
Security - Include security impact assessment
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

Check the troubleshooting guide
Review API documentation
Open an issue for bugs or feature requests

Built with TypeScript, Zod, and the Model Context Protocol