How to add Grafana Tempo MCP Server to Windsurf

Query distributed traces in Grafana Tempo with TraceQL (archived; Tempo now has embedded MCP). Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 15, 2026 · 90★ · stdio · no auth

Windsurf config for Grafana Tempo MCP Server

docker run -i --rm -e TEMPO_URL grafana/tempo-mcp-server

{
  "mcpServers": {
    "grafana-tempo-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TEMPO_URL",
        "grafana/tempo-mcp-server"
      ],
      "env": {
        "TEMPO_URL": "<your-tempo-query-endpoint>"
      }
    }
  }
}

Requires Docker to be installed and running.

Setup steps

1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
2Paste the Grafana Tempo MCP Server config below.
3Fill in placeholder secrets, then save.
4Click Refresh in the MCP panel.
5Grafana Tempo MCP Server's tools become available to Cascade.

Before you start

A running Grafana Tempo instance reachable at TEMPO_URL (defaults to http://localhost:3200)
Go 1.21+ to build from source, or Docker / Docker Compose to run it
No credential required by the server itself; optional basic-auth or bearer token if your Tempo endpoint is protected
An MCP client (Claude Desktop, Cursor, etc.) configured to launch the server over stdio

What Grafana Tempo MCP Server can do in Windsurf

tempo_query

Query Tempo for distributed traces using a TraceQL expression

Security

This repo is archived and superseded by Tempo's embedded MCP server, so prefer that for new work. Trace data can contain sensitive request attributes and IDs, so restrict the Tempo endpoint to trusted networks and add auth credentials when querying Grafana Cloud Tempo.

Grafana Tempo MCP Server + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the Grafana Tempo MCP Server config there under the "mcpServers" key and restart the client.

Is Grafana Tempo MCP Server safe to use with Windsurf?

Is this an official Grafana project?

No. It lives under a cold-storage org and is archived; Tempo's native/embedded MCP server in the main grafana/tempo repo is the official path.

Should I still use this server?

For new setups, prefer Tempo's embedded MCP server. This standalone server still works but is no longer maintained.

Does it need authentication?

The server itself requires no auth. It connects to Tempo via TEMPO_URL and optionally supports basic-auth or a bearer token for a protected Tempo endpoint.

View repo Full Grafana Tempo MCP Server page