Serena for Windsurf: Setup & Config

What you can do with Serena in Windsurf

Add symbol-aware IDE capabilities to coding agents instead of relying entirely on text search and edits.

• Edit symbol bodies and perform backend-supported refactorings.
• Debug interactively through the optional JetBrains backend.

Before you start: Serena in Windsurf

• uv
• An LLM client supporting MCP
• Additional language-specific dependencies where required

This command installs Serena; it is not the client launch command. Next run serena init, then configure your MCP client using the linked client guide. The default backend uses language servers. A separately started HTTP server is also supported, but no endpoint is stated in this README.

Serena Windsurf configuration

1. Choose Windsurf configuration scope

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

2. Add Serena to Windsurf

   Use the serena entry below in mcpServers. Keep Serena's documented stdio connection fields and your other Windsurf entries.

3. Check Serena in Windsurf

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

{
  "mcpServers": {
    "serena": {
      "command": "uv",
      "args": [
        "tool",
        "install",
        "-p",
        "3.13",
        "serena-agent"
      ],
      "env": {}
    }
  }
}

Serena tools available to Windsurf

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

search_for_pattern

After refreshing Serena in Windsurf settings, check Cascade's tool list for search_for_pattern.

replace_content

After refreshing Serena in Windsurf settings, check Cascade's tool list for replace_content.

list_dir

After refreshing Serena in Windsurf settings, check Cascade's tool list for list_dir.

Inspect directory entries.

find_file

After refreshing Serena in Windsurf settings, check Cascade's tool list for find_file.

read_file

After refreshing Serena in Windsurf settings, check Cascade's tool list for read_file.

Read complete files or selected portions.

execute_shell_command

After refreshing Serena in Windsurf settings, check Cascade's tool list for execute_shell_command.

Run shell tasks such as tests, builds, or linters.

Serena: full stored tool descriptions

Troubleshooting Serena in Windsurf

• Serena's uv tool install command installs a package, not a persistent MCP process. Confirm the upstream launch command before connecting Windsurf.
• Check uv on the machine running Windsurf's MCP integration for Serena; refresh MCP and inspect Cascade's tools.
• Known limitation: Semantic capabilities depend on the selected backend and language server.
• Known limitation: Interactive debugging and several advanced refactorings require the paid JetBrains plugin.
• Known limitation: Some languages need additional dependencies.
• General Windsurf troubleshooting lives in the /clients/windsurf guide.

Frequently asked questions