Grafana MCP Server
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.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Grafana MCP Server show me the CPU usage dashboard for the last hour"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
@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
Related MCP server: grafana-mcp-observability
๐ฆ Installation
Option 1: Global Installation
npm install -g @leval/mcp-grafanaOption 2: Run with npx (no installation)
npx @leval/mcp-grafanaOption 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.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.jsonLinux:
~/.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:
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)
{
"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:
Open Command Palette (
Cmd/Ctrl + Shift + P)Search for "Preferences: Open User Settings (JSON)"
Add the
claude.mcpServersconfiguration
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:
Open Cursor Settings (
Cmd/Ctrl + ,)Go to "Features" โ "AI" โ "MCP Servers"
Add the Grafana server configuration
Usage:
Press
Cmd/Ctrl + Kto 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:
{
"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:
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:
{
"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 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
# Test connection
curl -H "Authorization: Bearer YOUR_TOKEN" \
https://your-grafana.com/api/org
# Test with the MCP server
npx @leval/mcp-grafana --debugRun 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 transportConnection Issues
# Test your credentials
curl -H "Authorization: Bearer YOUR_TOKEN" \
https://your-grafana.com/api/org
# Check response - should return org detailsClient 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
npx @leval/mcp-grafana \
--disable-incident \
--disable-oncall \
--disable-siftCustom 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-grafanaDebug 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 PRFeature 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
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
Available Tools
43 toolsadd_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.
generate_deeplinkB
Generate deeplink URLs for Grafana resources. Supports dashboards, panels, and Explore queries
Inputs: resourceType (required), dashboardUid, datasourceUid, panelId, +2 more.
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
Scored across 43 tools
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.
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.
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.
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
Related MCP Connectors
Lets AI agents analyze API metrics, request logs, and traces, and manage apps and alerts.
Query your team's drift, vulnerability, and upgrade data from any AI assistant. OAuth 2.1, 51 tools.
Query your app's logs, metrics and incidents from your AI assistant.
Manage uptime monitors and incidents and search logs, metrics and traces from an AI assistant.
Related MCP Servers
- AlicenseCqualityDmaintenanceEnables 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.80131 npm1MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to query Grafana dashboards, alerts, and datasources for observability insights and incident investigation.MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to read Grafana dashboards, alert rules, and query datasources (Prometheus, Loki, etc.) through MCP tools, integrating Grafana monitoring into the IDE.2MIT
- AlicenseAqualityCmaintenanceEnables 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.6MIT