Serena MCP: Semantic Code Tools for Claude (2026 Guide)

TL;DR + what you actually need

If you only came for the copy-paste, here is the whole setup:

• One prerequisite: uv — the Python package manager Serena is distributed through. No API key, no account, no env vars.
• Two commands to install: uv tool install -p 3.13 serena-agent then serena init.
• One command per client: for Claude Code, claude mcp add --scope user serena -- serena start-mcp-server --context claude-code --project-from-cwd. For Codex, serena setup codex. For everything else, the install card below.
• Optional but worth it on big repos: serena project index before your first session, so the language server isn’t cold on your first find_symbol call.

What you get: the agent stops reading 400-line files to change one function. It asks the language server where the symbol is, reads only that, and edits only that. The rest of this guide explains why that matters, how the pieces fit, and where it bites.

What Serena actually does

Serena is a coding-agent toolkit shipped as an MCP server by Oraios AI. It exposes semantic code retrieval and editing tools — operations defined over symbols (functions, classes, methods, variables as the compiler sees them) rather than over lines of text.

The difference is concrete. Without Serena, an agent asked to rename a config-loading function does this: grep for the name, get 40 matches including comments and strings, read four full files to figure out which matches are real call sites, then patch each file with string replacement and hope none of the matches was a different symbol with the same name. Every step burns context tokens, and every step can be wrong, because grep matches text, not meaning.

With Serena, the same task is three tool calls: find_symbol to locate the definition, find_referencing_symbols to get the true call sites from the language server’s reference index, and rename_symbol to apply the rename everywhere at once. The language server already knows which identifiers resolve to which definitions — Serena hands that knowledge to the model instead of making it reconstruct the graph from raw text.

The project earned its reputation on Reddit before most directories listed it. The top thread on r/ClaudeAI (“Try out Serena MCP. Thank me later.”, 500+ upvotes) opens with a developer who had spent days hand-rolling grep, ast-grep, and tracing scripts to teach Claude his codebase’s structure — and found Serena “built exactly to solve that.” The maintainer’s own framing, from the launch-era post, is the cleanest one-liner on the project: “If you give me an IDE, I will obviously be better and faster at coding than if I had to code in something like Word and use pure file-reads and edits. Why shouldn’t the same hold for an LLM?”

Serena is also, deliberately, a context-efficiency play. Symbolic reads return a function body, not a file; overviews return signatures, not implementations. That philosophy — send the model the smallest artefact that answers the question — is the same one behind tool search and progressive disclosure, which we covered in our context-bloat deep dive. Serena applies it to the codebase itself.

How it works: language servers, symbols, projects

Four named pieces explain the whole system.

1. The language backend

Serena does not parse code itself. It launches language servers — the same LSP (Language Server Protocol) processes VS Code uses for go-to-definition — and translates their answers into MCP tool results. gopls for Go, clangd for C/C++, ruby-lsp for Ruby, and so on, with multiple servers running in parallel for polyglot repos. Since late 2025 there is a second, paid backend: a JetBrains plugin that swaps language servers for your JetBrains IDE’s analysis engine, adding refactorings (move, inline) and interactive debugging the LSP route doesn’t offer. The open-source LSP backend remains the default and is fully free.

2. Symbols and name paths

Every retrieval and edit tool addresses code by symbol name path — e.g. MyClass/my_method — not by line number. That’s what makes edits safe to compose: the agent can replace the body of UserService/authenticate without knowing or caring what line it starts on after the previous edit shifted everything by six lines. Line-based patching is where multi-step agent edits classically go wrong; symbol-based addressing removes the failure mode.

3. Projects, onboarding, memories

Serena is stateful: one project (a directory with a .serena/project.yml) is active at a time. On first activation it runs an onboarding pass — reading key files to learn the build system, test setup, and structure — and writes what it learned as memories: plain Markdown files in .serena/memories/ that you can read, edit, and commit like any other file. Future sessions start by listing memory names instead of re-reading the repo. It’s a deliberately minimal design — no vector store, no database — and it composes with whatever CLAUDE.md conventions you already follow from our Claude Code best-practices guide.

4. Contexts and modes

A context tells Serena what kind of client launched it, which changes the system prompt and the tool set. desktop-app (the default) ships every tool because Claude Desktop has none of its own; claude-code, codex, and ide strip the tools your agent already has — file reads, shell execution, line edits — so you don’t pay token-budget for duplicates. Modes (planning, editing, one-shot, interactive) layer on top and can be combined. Getting the context right is the single highest-leverage configuration decision — wrong context means duplicate tools, and duplicate tools mean the exact context bloat Serena is supposed to reduce.

Install (every client)

Serena is a stdio server: your MCP client launches it as a subprocess. The current documented install is a one-time CLI setup via uv:

# 1. Install uv (https://docs.astral.sh/uv)
# 2. Install the Serena CLI
uv tool install -p 3.13 serena-agent

# 3. Initialize (downloads what the default backend needs)
serena init

# Later: upgrade
uv tool upgrade serena-agent

After that, every client config boils down to one launch command: serena start-mcp-server plus a --context flag. The install card below pulls configs from the canonical /servers/serena catalog entry for each client:

One-line install · Serena

Open server page

Install

Cursor

One-click install

1-Click

VS Code

One-click install

1-Click

Claude Desktop

Copy configuration

Claude Code

Copy CLI command

CLI

Gemini

Copy CLI command

CLI

Codex

Copy CLI command

CLI

Windsurf

Copy configuration

ChatGPT

Add via Settings → Connectors

M

Manual

Copy configuration

One compatibility note before the per-client details: older tutorials (and older catalog snippets) launch Serena as uvx --from git+https://github.com/oraios/serena serena-mcp-server --context ide-assistant. Two things have been renamed since: the entry point is now the serena CLI with the start-mcp-server subcommand, and the ide-assistant context is deprecated — current releases map it to claude-code with a warning. If a snippet you copied references either old name, update it to the forms below.

Claude Code

The fast path is the built-in setup command, which writes the config for you:

serena setup claude-code

Or register manually — global for all projects:

claude mcp add --scope user serena -- serena start-mcp-server --context claude-code --project-from-cwd

Or per-project:

claude mcp add serena -- serena start-mcp-server --context claude-code --project "$(pwd)"

--project-from-cwd walks up from the directory Claude Code was started in and activates the nearest directory containing .serena/project.yml or .git — which is what you want for a CLI agent. Verify with /mcp inside the session. The Serena docs also ship optional Claude Code hooks (serena-hooks remind / activate / cleanup) that nudge the agent back to symbolic tools when it drifts into consecutive grep-and-read calls — worth adding if you notice Serena’s tools going unused. Full client reference at /clients/claude-code.

Codex CLI

serena setup codex, or add this to ~/.codex/config.toml:

[mcp_servers.serena]
startup_timeout_sec = 15
command = "serena"
args = ["start-mcp-server", "--project-from-cwd", "--context=codex"]

Claude Desktop

Settings → Developer → MCP Servers → Edit Config, then add to claude_desktop_config.json:

{
  "mcpServers": {
    "serena": {
      "command": "serena",
      "args": ["start-mcp-server"]
    }
  }
}

No context flag needed — the default desktop-app context is built for Claude Desktop and ships the full tool set, including file operations and shell execution that Desktop lacks. Because Desktop has a global (not per-workspace) config, you activate projects conversationally: “Activate /path/to/my-project as a project using Serena.”

Cursor, VS Code, Windsurf

Use serena start-mcp-server --context=ide (VS Code has its own --context=vscode) with --project pointing at the workspace folder. In VS Code, run the MCP: Add Server command and pick the stdio option. The ide context excludes read_file, create_text_file, list_dir, find_file, and execute_shell_command — your editor agent already has all five.

Remote / shared (streamable HTTP)

serena start-mcp-server --transport streamable-http --port 9121
# then point your client at http://localhost:9121/mcp

Use this only when every connected client works on the same project — Serena is stateful and holds one active project at a time. For multiple agents on multiple repos, give each its own stdio instance.

Tools walkthrough

Tool names below are from the current source; which ones are actually exposed depends on your context. Grouped by job:

Reading the symbol graph

• get_symbols_overview — the shape of a file: classes, functions, methods as a tree, no bodies. The token-cheap replacement for “read the file to see what’s in it.”
• find_symbol — locate a symbol by name path (e.g. UserService/authenticate), optionally returning its body. The workhorse.
• find_referencing_symbols — every real call site of a symbol, from the language server’s reference index. The tool grep pretends to be.
• find_implementations / find_declaration — interface-to-impl navigation and the reverse.
• get_diagnostics_for_file — compiler and linter errors via LSP, so the agent can check its own edit without running a build.

Editing at the symbol level

• replace_symbol_body — swap exactly one function or class body. The edit primitive that makes “change this function” a single atomic operation.
• insert_after_symbol / insert_before_symbol — add a new function or import relative to an existing symbol, no line math.
• rename_symbol — LSP-powered rename across the project.

Plain-file fallbacks

search_for_pattern (regex search), replace_content, read_file, create_text_file, list_dir, find_file, and execute_shell_command exist for non-code files and for clients with no tools of their own. Coding-agent contexts disable most of these — by design, so the model isn’t choosing between two read tools.

Memory and workflow

write_memory, read_memory, list_memories, edit_memory, rename_memory, delete_memory manage the Markdown memory store. A set of workflow tools (onboarding, plus think_about_* self-check prompts) steer the agent through project familiarization and task-adherence checks. activate_project and switch_modes handle session state in multi-project contexts.

Recipes

Recipe 1 — Orient in a codebase you’ve never seen

Prompt: “Using Serena, give me an overview of the payment module: list the symbols in src/payments/, then show the signature and docstring of the main entry points. Don’t read full files.” The agent chains list_dir → get_symbols_overview → find_symbol with bodies off. On a module that would cost 30k tokens to read raw, the overview round-trip typically comes back in a few hundred — and the model reasons over structure instead of noise.

Recipe 2 — Impact analysis before a refactor

Prompt: “Find every caller of OrderService/calculate_totals and tell me which ones would break if I add a required currency parameter.” find_referencing_symbols returns true call sites with surrounding code. This is the query grep cannot answer on a method name like get or process — the reference index disambiguates by resolution, not by string.

Recipe 3 — Token-frugal edit loop

Prompt: “Replace the body of RateLimiter/check with a sliding-window implementation, then run diagnostics on the file.” The agent calls find_symbol (read one body), replace_symbol_body (write one body), get_diagnostics_for_file (verify). Three calls, no whole-file reads, no line-number drift between steps. This loop is where Serena’s token savings concentrate.

Recipe 4 — Persistent project knowledge

After a long debugging session: “Write a memory called modules/billing-quirks summarizing what we learned about the invoice rounding behavior.” Next week’s session starts with that memory name visible and readable on demand — committed to git, reviewable in a PR, editable by hand. Onboarding tip from the docs: the first onboarding pass fills a lot of context, so start a fresh conversation once it completes.

Supported languages

The README currently lists out-of-the-box support for over 40 languages via the LSP backend. The mainstream set — Python, TypeScript/JavaScript, Go, Rust, Java, C/C++, C#, PHP, Ruby, Kotlin, Swift, Dart, Elixir, Clojure, Bash — works with little or no extra setup. The long tail (Ada, Erlang, Fortran, GDScript, OCaml, Scala, and more) is documented per-language, and some entries need a one-time install or a running companion: gopls for Go, pip install fortls for Fortran, a running Godot editor for GDScript, a compile_commands.json for best C/C++ results.

Three details worth knowing. Polyglot repos can run multiple language servers in parallel, and you can toggle languages live from the dashboard. Monorepos get cross-package references via additional_workspace_folders in project.yml — currently TypeScript-only. And the paid JetBrains backend sidesteps the language-server matrix entirely: anything a JetBrains IDE can analyze, Serena can use, except Rider and CLion. Check the language-support page for your stack’s specifics before assuming.

Limits + gotchas

The token-usage debate is real — read both sides

Serena’s pitch is token efficiency, yet a recurring r/ClaudeCode thread reports the opposite: hitting context limits faster with Serena enabled. Both observations are consistent. Every MCP server’s tool descriptions ride along in every request — one commenter put it plainly: every MCP has to explain its tools to the model, and that costs context before you’ve done anything. Add the onboarding pass and a small project can come out behind. The savings are back-loaded: they show up on large codebases, long sessions, and repeated symbol-level edits. A skeptical r/ClaudeAI thread (“Am I the only one not finding any value in Serena?”) reads, in our view, mostly as small-project experience. Our take: under ~20k lines of code, skip it; past that, it pays for itself.

The dashboard opens a browser tab by default

Every server start opens the web dashboard (http://localhost:24282/dashboard/index.html) unless told otherwise. It’s genuinely useful — live logs, tool-call statistics, on-the-fly config and memory editing — but the auto-open surprises people and breaks headless setups. Disable the auto-open with web_dashboard_open_on_launch: False in ~/.serena/serena_config.yml or --open-web-dashboard False on the launch command; keep the dashboard itself enabled.

First-call latency on unindexed projects

Language servers need to analyze the project before they can answer. On a large repo, the first symbolic call of a session can stall long enough to look like a hang — and slow startup can even trip Claude Code’s MCP timeout. Run serena project index ahead of time and set MCP_TIMEOUT=60000 if your client gives up too early.

Claude Code’s bias toward built-in tools

The Serena docs are unusually candid here: recent Claude Code builds describe their built-in tools at such length (~16k tokens of descriptions) that the model strongly prefers them over MCP tools, and the maintainers ship a counter-measure — a system-prompt override (claude --system-prompt="$(serena prompts print-cc-system-prompt-override)") plus the reminder hooks. If you install Serena and never see its tools called, this is why, and those are the fixes.

What we got wrong

Two assumptions we had to walk back. First, we assumed onboarding was skippable ceremony and turned it off — then watched the agent re-derive the build system every session; the memories it writes are the cheap version of that work, done once. Second, we ran the default context inside Claude Code “to have all the tools available.” That gave the model two read tools, two edit tools, and a shell it already had — measurably worse tool selection, plus wasted context. The maintainers added per-client contexts for a reason; use them.

Troubleshooting

Alternatives — and when to pick them

• Claude Code built-ins (no MCP): for small repos, Grep + Read + Edit are honestly fine, and zero extra context cost. The maintainers themselves dropped Serena’s regex-replace tool from the claude-code context because Claude Code’s editor is good enough. Add Serena when the codebase outgrows text search.
• The JetBrains backend: not a competitor but Serena’s own paid tier — worth it if you live in IntelliJ/PyCharm and want move/inline refactorings and debugging tools the LSP backend can’t provide.
• Docs-retrieval MCPs (Context7, DeepWiki): orthogonal, and commonly run alongside Serena — they feed the model external library knowledge while Serena feeds it your repo’s structure.

Serena also sits near the top of our awesome MCP servers roundup for the coding category — see that post for how it stacks against the rest of the ecosystem.

FAQ

Sources

• Primary — repository: github.com/oraios/serena (MIT, Oraios AI)
• Primary — official docs (install, clients, configuration, dashboard, memories): oraios.github.io/serena
• Community — r/ClaudeAI: “Try out Serena MCP. Thank me later.”
• Community (maintainer) — r/ClaudeAI: “Claude and Serena MCP — a dream team for coding” and “Major Serena MCP Updates”
• Contrarian — r/ClaudeCode: token-usage thread and r/ClaudeAI: “not finding any value”
• Canonical MCP.Directory entry: /servers/serena
• Related reading: the context-bloat fix, Claude Code best practices

Note: we could not verify a first-party Serena announcement on X at the time of writing, so no tweet is embedded; the maintainers’ Reddit posts above serve as the first-party voice.