How to add Serena to Windsurf

LSP-powered coding agent toolkit: semantic symbol search, references and structural edits. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 15, 2026 · 12k★ · stdio · no auth

Windsurf config for Serena

uvx --from git+https://github.com/oraios/serena serena start-mcp-server

{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/oraios/serena",
        "serena",
        "start-mcp-server"
      ]
    }
  }
}

Requires `uv` (the Python package runner). Install it from https://docs.astral.sh/uv/ if `uvx` is not found.

Setup steps

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

Before you start

uv (the Python package/tool manager) installed — it bootstraps and runs Serena
Python 3.11+ (the project targets recent Python; 3.13 recommended)
Language servers for the languages you use are auto-downloaded on first use; some ecosystems (e.g. Java, C#) may need their toolchain installed
No API key or account required — Serena runs locally against your repo

What Serena can do in Windsurf

find_symbol

Locate a class/function/symbol by name path across the project

get_symbols_overview

Return the symbol outline (top-level definitions) of a file

find_referencing_symbols

Find all symbols that reference a given symbol (call sites, usages)

replace_symbol_body

Replace the full body of a function/class/method symbol

insert_after_symbol

Insert new code immediately after a given symbol

insert_before_symbol

Insert new code immediately before a given symbol (e.g. imports)

search_for_pattern

Regex/text search across the project for non-symbol matches

read_file / list_dir / find_file

Navigate the project tree and read file contents

Security

Serena reads and edits files in the project you point it at and launches language servers locally, so only run it on trusted codebases. Installing from a git ref pulls executable code, so pin to a tag or commit you trust.

Serena + Windsurf FAQ

Where is the Windsurf config file?

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

Is Serena safe to use with Windsurf?

Does Serena require an API key or account?

No. Serena runs entirely locally against your code via uv/uvx and language servers. There is no authentication, account, or hosted service.

Which languages does it support?

40+ languages through their language servers, including Python, TypeScript/JavaScript, Java, Go, Rust, C/C++, C#, PHP, and Ruby. Language servers are downloaded automatically on first use.

Which MCP clients work with Serena?

Any stdio MCP client — including Claude Code, Claude Desktop, Codex, Cursor, and VS Code. There's also a JetBrains plugin path with additional refactoring tools.

View repo Full Serena page