1. Home
  2. Grafana MCP Server
  3. Grafana MCP Server for Windsurf: Setup & Config

Data as of

Grafana MCP Server for Windsurf: Setup & Config

Windsurf: Connect MCP assistants to Grafana dashboards, datasources, alerts, and incident workflows.

What you can do with Grafana in Windsurf

Choose it to investigate and manage Grafana observability resources from an MCP assistant.

  • Investigate service behavior using Grafana metrics, logs, and traces.
  • Add investigation notes to incidents and inspect on-call coverage.

Before you start: Grafana in Windsurf

  • uv
  • Grafana 9.0 or later for full functionality
  • An MCP client
  • A configured Grafana connection and service-account token

The README's quick start uses uvx. Set the instance URL for local Grafana or Grafana Cloud. Several optional query groups and administrative tools are disabled by default.

Grafana Windsurf configuration

  1. Choose Windsurf configuration scope

    For Grafana MCP Server, open macOS/Linux: ~/.codeium/windsurf/mcp_config.json Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json. Merge into mcpServers; remote endpoints use serverUrl.

  2. Add Grafana MCP Server to Windsurf

    Use the mcp-grafana entry below in mcpServers. Keep Grafana MCP Server's documented stdio connection fields and your other Windsurf entries.

  3. Check Grafana MCP Server in Windsurf

    Grafana MCP Server: Refresh MCP in Windsurf settings and inspect Cascade’s tools.

Config file · macOS/Linux: ~/.codeium/windsurf/mcp_config.json

Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json

JSON
{
  "mcpServers": {
    "mcp-grafana": {
      "command": "uvx",
      "args": [
        "mcp-grafana"
      ],
      "env": {
        "GRAFANA_URL": "<URL of your Grafana instance>",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<Grafana service-account token>"
      }
    }
  }
}

Grafana tools available to Windsurf

Grafana's stored tool list documents 40 tools; compare it with Windsurf's connected tool list, because the stored list is not a live check.

add_activity_to_incident

After refreshing Grafana in Windsurf settings, check Cascade's tool list for add_activity_to_incident.

alerting_manage_routing

After refreshing Grafana in Windsurf settings, check Cascade's tool list for alerting_manage_routing.

alerting_routing_write

After refreshing Grafana in Windsurf settings, check Cascade's tool list for alerting_routing_write.

alerting_rules_read

After refreshing Grafana in Windsurf settings, check Cascade's tool list for alerting_rules_read.

alerting_rules_write

After refreshing Grafana in Windsurf settings, check Cascade's tool list for alerting_rules_write.

alerting_silences_read

After refreshing Grafana in Windsurf settings, check Cascade's tool list for alerting_silences_read.

alerting_silences_write

After refreshing Grafana in Windsurf settings, check Cascade's tool list for alerting_silences_write.

analyze_loki_labels

After refreshing Grafana in Windsurf settings, check Cascade's tool list for analyze_loki_labels.

check_datasources_health

After refreshing Grafana in Windsurf settings, check Cascade's tool list for check_datasources_health.

create_annotation

After refreshing Grafana in Windsurf settings, check Cascade's tool list for create_annotation.

create_datasource

After refreshing Grafana in Windsurf settings, check Cascade's tool list for create_datasource.

Review a datasource plugin schema, then create a datasource from approved field values.

create_folder

After refreshing Grafana in Windsurf settings, check Cascade's tool list for create_folder.

Add a Grafana folder with a title and optional identifier.

create_incident

After refreshing Grafana in Windsurf settings, check Cascade's tool list for create_incident.

Open an incident with severity and contextual fields; creation may notify responders.

create_snapshot

After refreshing Grafana in Windsurf settings, check Cascade's tool list for create_snapshot.

Generate a dashboard snapshot with optional expiry settings.

delete_annotation

After refreshing Grafana in Windsurf settings, check Cascade's tool list for delete_annotation.

Permanently remove an annotation by identifier.

delete_snapshot

After refreshing Grafana in Windsurf settings, check Cascade's tool list for delete_snapshot.

Remove a snapshot using its key.

diff_tempo_traces

After refreshing Grafana in Windsurf settings, check Cascade's tool list for diff_tempo_traces.

Compare complete traces and return a summary with optional span-level differences.

generate_deeplink

After refreshing Grafana in Windsurf settings, check Cascade's tool list for generate_deeplink.

Build links to dashboards, panels, or preconfigured Explore queries.

get_alert_group

After refreshing Grafana in Windsurf settings, check Cascade's tool list for get_alert_group.

Inspect an OnCall alert group and the latest available alert payload.

get_annotation_tags

After refreshing Grafana in Windsurf settings, check Cascade's tool list for get_annotation_tags.

Retrieve annotation tags with optional name matching.

get_annotations

After refreshing Grafana in Windsurf settings, check Cascade's tool list for get_annotations.

get_assertions

After refreshing Grafana in Windsurf settings, check Cascade's tool list for get_assertions.

get_current_oncall_users

After refreshing Grafana in Windsurf settings, check Cascade's tool list for get_current_oncall_users.

get_dashboard_by_uid

After refreshing Grafana in Windsurf settings, check Cascade's tool list for get_dashboard_by_uid.

get_dashboard_panel_queries

After refreshing Grafana in Windsurf settings, check Cascade's tool list for get_dashboard_panel_queries.

get_dashboard_property

After refreshing Grafana in Windsurf settings, check Cascade's tool list for get_dashboard_property.

get_dashboard_summary

After refreshing Grafana in Windsurf settings, check Cascade's tool list for get_dashboard_summary.

get_datasource

After refreshing Grafana in Windsurf settings, check Cascade's tool list for get_datasource.

get_doc

After refreshing Grafana in Windsurf settings, check Cascade's tool list for get_doc.

get_incident

After refreshing Grafana in Windsurf settings, check Cascade's tool list for get_incident.

get_oncall_shift

After refreshing Grafana in Windsurf settings, check Cascade's tool list for get_oncall_shift.

Read the details of a specific scheduled OnCall shift.

get_panel_image

After refreshing Grafana in Windsurf settings, check Cascade's tool list for get_panel_image.

Render a panel, dashboard, or Explore view as a PNG using Grafana Image Renderer.

get_plugin

After refreshing Grafana in Windsurf settings, check Cascade's tool list for get_plugin.

Check a Grafana plugin's installation and version details.

get_snapshot

After refreshing Grafana in Windsurf settings, check Cascade's tool list for get_snapshot.

Retrieve a snapshot's metadata and dashboard payload by key.

get_tempo_trace

After refreshing Grafana in Windsurf settings, check Cascade's tool list for get_tempo_trace.

Fetch a Tempo trace using its identifier.

get_tempo_traceql_docs

After refreshing Grafana in Windsurf settings, check Cascade's tool list for get_tempo_traceql_docs.

Read TraceQL syntax guidance and examples before composing trace queries.

grafana_api_request

After refreshing Grafana in Windsurf settings, check Cascade's tool list for grafana_api_request.

Call Grafana API endpoints with authentication and optional response filtering.

install_plugin

After refreshing Grafana in Windsurf settings, check Cascade's tool list for install_plugin.

Look up a plugin's latest version or install an explicitly supplied version.

list_alert_groups

After refreshing Grafana in Windsurf settings, check Cascade's tool list for list_alert_groups.

Find OnCall alert groups by state, integration, team, labels, or time range.

list_dashboard_versions

After refreshing Grafana in Windsurf settings, check Cascade's tool list for list_dashboard_versions.

List saved dashboard versions and their authors, timestamps, and messages.

Grafana: full stored tool descriptions

Troubleshooting Grafana in Windsurf

  • Check uvx mcp-grafana (from uv, for Python tools) on the machine running Windsurf's MCP integration for Grafana MCP Server; refresh MCP and inspect Cascade's tools.
  • Check GRAFANA_SERVICE_ACCOUNT_TOKEN, GRAFANA_URL for Grafana MCP Server; do not bypass a Windsurf permission error with a broad administrator token.
  • Grafana MCP Server uses stdio here: Windsurf must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
  • Known limitation: Full functionality requires Grafana 9.0 or newer.
  • Known limitation: Some query and administrative groups need explicit enabling.
  • Known limitation: Rendering and datasource features have additional service prerequisites.
  • General Windsurf troubleshooting lives in the /clients/windsurf guide.

Grafana MCP Server — details. Windsurf guide

Frequently asked questions

Windsurf reads Grafana MCP Server under mcpServers in ~/.codeium/windsurf/mcp_config.json on macOS/Linux; Windows uses %USERPROFILE%\.codeium\windsurf\mcp_config.json.

Windsurf's mcp-grafana example uses stdio.

Grafana MCP Server's Windsurf configuration invokes uvx mcp-grafana (from uv, for Python tools).

Windsurf's Grafana MCP Server example references GRAFANA_SERVICE_ACCOUNT_TOKEN, GRAFANA_URL. Check these names if startup or authentication fails; the example alone does not distinguish required from optional values.

Grafana MCP Server's stored list contains 40 tools, including add_activity_to_incident, alerting_manage_routing, alerting_routing_write. Compare those names with Windsurf's connected tool list; the stored list is not a live check.

Use the compact summary or JSONPath property tool rather than requesting the entire dashboard.

The supplied tool description requires the Grafana Image Renderer service.