Grafana MCP Server

Decide which MCP server implementation to use based on your hosting and authentication needs:

Use the open source server documentation for self-managed or manual deployments. For the hosted version, refer to the Grafana Cloud MCP server documentation.

When creating new documentation articles, use a named Markdown file where the filename is the page title slug (using dashes). Use the following frontmatter and structure:

---
title: Topic title
menuTitle: Short title
description: Description
keywords:
  - keyword
weight: 1
aliases:
  - /old-url/
---

# Topic title

Introduction providing overview of goals and content.

## What you'll achieve

Overview of outcomes (if relevant).

## Before you begin

List requirements.

## <ACTION_VERB_HEADING>

Start headings with verbs. Don't use "Step X:" in headings.

## Next steps

Links to related articles (if relevant). Don't use "refer to" syntax.

For section _index.md pages (excluding the home page), use this template:

---
# Same article frontmatter
---

# Section title

Introduction providing goals and content.

{{< section withDescriptions="true" >}}

Before writing complex PromQL expressions, you can use the MCP server to explore available metadata. You can ask your AI assistant to:

• List metric names.
• List label names.
• List label values for a specific selector.

The server uses the Prometheus API to fetch this metadata, enabling discovery of what metrics and labels are available in your datasource.

If you only need a specific part of a dashboard (such as a single panel's configuration), use the get_dashboard_property tool. Provide a JSONPath expression to fetch only the requested data, which prevents loading the entire dashboard JSON.

Example JSONPath expression: $.panels[0].title

Releases follow a branch-based workflow. If you are not using the automated /draft-release command, follow these manual steps:

1. Determine the next version: Identify the next version based on the latest git tag.
2. Create a release branch: Checkout a new branch named release/vX.Y.Z from main.
3. Update CHANGELOG.md: Add entries for the new version following the Keep a Changelog format.
4. Commit and Push: Commit the changes and push the branch to origin.
5. Create a PR: Open a Pull Request for review.
6. Merge and Tag: After merging the PR, if the auto-tag.yml workflow is not configured, you must manually tag and push the version:

git checkout main && git pull
git tag vX.Y.Z HEAD
git push origin vX.Y.Z

To use docs.agent, run your preferred CLI AI agent within the repository and provide the following instruction to trigger its behavior:

Follow docs/agent/rules.md

Once active, the agent can be used to automatically scope work, update context and plans, and author documentation content.

To use the Grafana MCP server within the Windsurf IDE, ensure you have the following prerequisites:

• Windsurf IDE installed
• Grafana 9.0+ with a service account token
• mcp-grafana binary available in your system PATH

You can configure the server either through the Windsurf UI (Cmd+Shift+P -> Open Windsurf Settings -> Cascade section -> Add Server) or by manually editing the configuration file located at:

• macOS/Linux: ~/.codeium/windsurf/mcp_config.json
• Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json

The MCP server requires specific Grafana RBAC permissions and scopes to function. When creating a service account:

1. Grant Minimum Permissions: Assign only the actions required for the tools you enable.
2. Matching Scopes: Ensure permissions are paired with appropriate scopes (e.g., datasources:*, dashboards:*).
3. Quick Setup: For faster configuration, assign the built-in Editor role to the service account. This provides broad read/write access suitable for most MCP operations, though it is less granular than a least-privilege approach.

Special Note for Grafana Incident and Sift tools: These use basic roles rather than fine-grained RBAC:

• Viewer: Read-only (e.g., list incidents, get investigations).
• Editor: Write operations (e.g., create incidents, run analyses that modify state).

The server exports structured logs via OTLP/gRPC when OTEL_EXPORTER_OTLP_ENDPOINT (or OTEL_EXPORTER_OTLP_LOGS_ENDPOINT) is set. Logs include trace_id and span_id for correlation with traces. Traces and logs can be enabled independently by using their specific environment variables. Logs are also exported under the stdio transport. If the collector is unreachable, logs are buffered in memory (default queue: 2048) before being dropped.

# Send logs and traces to a local OTel collector
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 \
OTEL_EXPORTER_OTLP_INSECURE=true \
./mcp-grafana -t streamable-http