Provides comprehensive tools for interacting with Grafana instances, including dashboard management, data source configuration, Prometheus queries, Loki log analysis, incident management, alerting, on-call scheduling, and performance profiling through 43 different tools.
Enables execution of PromQL queries, retrieval of metric metadata, and exploration of metric names, labels, and their values from Prometheus data sources within Grafana.
@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.
๐ 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
๐ฆ Installation
Option 1: Global Installation
Option 2: Run with npx (no installation)
Option 3: Local Development
๐ง Configuration
Environment Variables
Create a .env
file in your project root:
๐ค 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:
Usage:
Save the configuration file
Restart Claude Desktop
Look for the MCP icon (๐) in the interface
Ask Claude: "What dashboards are available in my Grafana?"
Claude Code (VS Code Extension)
Or configure globally in VS Code settings:
Open Command Palette (
Cmd/Ctrl + Shift + P
)Search for "Preferences: Open User Settings (JSON)"
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:
Or configure globally:
Open Cursor Settings (
Cmd/Ctrl + ,
)Go to "Features" โ "AI" โ "MCP Servers"
Add the Grafana server configuration
Usage:
Press
Cmd/Ctrl + K
to open AI chatThe 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
:
Usage:
Open Assistant panel (
Cmd/Ctrl + ?
)The MCP server starts automatically
Ask: "List all datasources and their types"
Codex (GitHub Copilot Workspace)
Configuration: Add to .github/codex/mcp-config.json
:
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
:
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
:
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 for dashboards | "Find dashboards with 'cpu' in the name" |
| Get complete dashboard JSON | "Show me the dashboard with UID abc123" |
| Get dashboard metadata | "Summarize the monitoring dashboard" |
| Extract specific properties | "Get all panel titles from dashboard xyz" |
| Create or update dashboards | "Add a new panel to track memory usage" |
Data Sources (3 tools)
Tool | Description | Example Usage |
| List all datasources | "What datasources are configured?" |
| Get datasource by UID | "Show details for datasource uid-123" |
| Get datasource by name | "Get the Prometheus datasource config" |
Prometheus (5 tools)
Tool | Description | Example Usage |
| Execute PromQL queries | "Show CPU usage for the last hour" |
| List available metrics | "What metrics are available?" |
| List label names | "Show all Prometheus labels" |
| Get label values | "What values exist for the 'env' label?" |
| Get metric metadata | "Describe the node_cpu_seconds metric" |
Loki Logs (5 tools)
Tool | Description | Example Usage |
| Execute LogQL queries | "Show error logs from the API service" |
| Get log stream statistics | "How many log entries in the last day?" |
| List log label names | "What labels are in our logs?" |
| Get log label values | "Show all namespaces in logs" |
| Find error patterns | "Analyze error patterns in production" |
Incident Management (4 tools)
Tool | Description | Example Usage |
| List incidents | "Show all active incidents" |
| Get incident details | "Details for incident INC-123" |
| Create new incident | "Create a critical incident for API outage" |
| 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
Creating a Service Account Token (Recommended)
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
Required Permissions:
dashboards:read
- View dashboardsdatasources:read
- View datasourcesalert.rules:read
- View alert ruleslogs:read
- Query Lokimetrics:read
- Query Prometheusincidents: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
Run Test Suite
๐ 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
Connection Issues
Client Not Detecting Server
Verify configuration file location
Check JSON syntax is valid
Restart the client application
Look for MCP indicator in UI
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
Custom TLS Configuration
Debug Mode
๐ค Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
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
๐ Support
NPM Package: npmjs.com/package/@leval/mcp-grafana
GitHub Issues: github.com/levalhq/mcp-grafana/issues
Documentation: Grafana Docs
MCP Protocol: modelcontextprotocol.io
๐ 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
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.
Tools
Enables AI assistants to interact with Grafana dashboards, datasources, alerts, incidents, and monitoring data through 43 comprehensive tools. Supports querying Prometheus metrics, Loki logs, managing incidents, and dashboard operations with full authentication support.