---
title: "Windsurf | Grafana documentation"
description: "Set up the Grafana MCP server for Windsurf."
---

# Windsurf

This guide helps you set up the `mcp-grafana` server for Windsurf.

## Prerequisites

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

## Configuration

Configuration file location:

Expand table

| OS          | Path                                              |
|-------------|---------------------------------------------------|
| macOS/Linux | `~/.codeium/windsurf/mcp_config.json`             |
| Windows     | `%USERPROFILE%\.codeium\windsurf\mcp_config.json` |

### Add using the UI

1. Open Windsurf Settings (Cmd+Shift+P -> **Open Windsurf Settings**)
2. Scroll to Cascade section
3. Click **Add Server** or **View raw config**

### Manual configuration

Create or edit `~/.codeium/windsurf/mcp_config.json`:

JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```json
{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your-token>"
      }
    }
  }
}
```

### Docker configuration

JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```json
{
  "mcpServers": {
    "grafana": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "GRAFANA_URL",
        "-e",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN",
        "grafana/mcp-grafana",
        "-t",
        "stdio"
      ],
      "env": {
        "GRAFANA_URL": "http://host.docker.internal:3000",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your-token>"
      }
    }
  }
}
```

## Debug mode

JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```json
{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": ["-debug"],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your-token>"
      }
    }
  }
}
```

## Verify configuration

1. Click the refresh button after adding the server
2. Open Cascade view
3. Click the hammer icon (MCP servers)
4. Grafana should show green status
5. Ask: “List my Grafana dashboards”

## Tool limit

Windsurf limits total MCP tools to 100. If you hit the limit:

1. Go to Windsurf Settings -&gt; Manage plugins
2. Disable unused servers
3. Toggle off individual tools you don’t need

## Troubleshooting

**Server not connecting:**

- Press refresh button in Cascade settings
- Check JSON syntax
- Verify binary exists: `which mcp-grafana`

**SSE transport (remote server):**

If you need HTTP-based connection instead of stdio:

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
mcp-grafana --transport streamable-http --address localhost:8000
```

Then configure with `serverUrl`:

JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```json
{
  "mcpServers": {
    "grafana": {
      "serverUrl": "http://localhost:8000/mcp"
    }
  }
}
```

## Read-only mode

JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```json
{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": ["--disable-write"],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your-token>"
      }
    }
  }
}
```

## Next steps

- [Set up](../../set-up/) for other install options.
- [Configure authentication](../../configure/authentication/) for Grafana credentials.