Serena MCP Review: An LSP-Powered IDE for AI Agents

TL;DR

Serena is an open-source MCP toolkit that turns your AI coding agent into something that behaves like a developer using a real IDE — instead of one frantically grepping a codebase. It plugs into Claude Code, Codex, Cursor, JetBrains, Copilot, OpenCode, and any other Model Context Protocol client and gives them symbol-level retrieval, refactoring, and editing tools backed by Language Server Protocol (LSP) servers.

Key facts:

• 23,750+ GitHub stars with ~1,500 added in the last week
• MIT licensed, Python, maintained by oraios
• 40+ programming languages supported via LSP — Python, TypeScript, Rust, Go, Java, C#, Swift, Kotlin, Elixir, Zig, and many more
• Two backends: free LSP (default) or paid JetBrains plugin (free trial) for IntelliJ-grade refactoring
• Symbol-aware tools: find_symbol, find_referencing_symbols, replace_symbol_body, insert_after_symbol, rename, safe_delete
• Memory system for long-lived agent workflows across sessions
• Installs in one command with uv tool install -p 3.13 serena-agent@latest --prerelease=allow
• Works in stdio or HTTP/SSE mode — local launch or remote MCP server
• Honest limitation: language servers must be installed and running; some features (move, inline, type hierarchy) only work with the paid JetBrains backend

If you’ve watched Claude Code burn 30K tokens reading entire files just to rename one function, Serena is the missing layer that lets it ask “where is User.from_dict defined?” and “who calls it?” the way a human dev would.

Quick Reference

Field	Value
Repo	oraios/serena
Docs	oraios.github.io/serena
Install	uv tool install -p 3.13 serena-agent@latest --prerelease=allow
Init	serena init
Backends	Language Server Protocol (free) / JetBrains Plugin (paid)
Languages	40+ via LSP, all JetBrains-supported via plugin
License	MIT
Created	March 2025
MCP transports	stdio, HTTP, SSE
Compatible clients	Claude Code, Codex, Cursor, Claude Desktop, OpenCode, Gemini CLI, JetBrains AI, Copilot, Junie, OpenWebUI

What Serena Actually Is

Serena is not a coding agent. It is the tool belt that turns a coding agent — Claude Code, Codex, Cursor, whatever — from a clever string-matcher into something that understands code structure.

The short version: Serena is the bridge between MCP-speaking LLMs and Language Server Protocol servers. LSP is the same protocol VS Code, Neovim, and JetBrains use to power “go to definition”, “find references”, “rename symbol”, and “show diagnostics”. Serena exposes that power as MCP tools.

When your agent needs to rename getUserById across 47 files in a TypeScript monorepo:

• Without Serena: the agent reads files, writes regex, replaces getUserById everywhere — including comments, string literals in SQL templates, and an unrelated method on another class also called getUserById. Then runs the build, sees errors, retries, gives up around iteration 4.
• With Serena: the agent calls find_symbol("getUserById"), gets the canonical definition, calls find_referencing_symbols, gets every real call site (no false positives), then calls rename and the language server handles the edit atomically.

Why It’s Trending Right Now

Three factors pushed Serena from niche-MCP-tool to ~24K stars in 14 months:

1. MCP went mainstream. When Claude Code, Codex, and Cursor all converged on Model Context Protocol in late 2025, MCP servers became the unit of agent capability. Serena was already there with a polished, working implementation when most “MCP servers” were one-off scripts.

2. Coding-agent users hit the context wall. A flurry of Reddit threads — “Try out Serena MCP. Thank me later” in r/ClaudeAI got hundreds of upvotes — describe the same problem: agents waste context reading entire files when they only need one function. Serena’s symbol-level tools cut that waste dramatically.

3. Real evaluation results. The Serena team published unbiased agent-vs-agent comparisons. Their key quote, from an Opus 4.6 evaluation on a large Python codebase, became the project’s tagline:

“Serena’s IDE-backed semantic tools are the single most impactful addition to my toolkit – cross-file renames, moves, and reference lookups that would cost me 8–12 careful, error-prone steps collapse into one atomic call.”

GPT-5.4 in Codex CLI on a Java codebase landed in the same place: “It gives me the missing IDE-level understanding of symbols, references, and refactorings, turning fragile text surgery into calmer, faster, more confident code changes.” When agents from different vendors independently endorse a tool, that is unusual signal.

Installation: From Zero to Working

The official guidance is loud about one thing: do not install Serena from MCP marketplaces. Their commands are stale. Follow the canonical path.

# Prerequisite: install uv (https://docs.astral.sh/uv)
# Then:
uv tool install -p 3.13 serena-agent@latest --prerelease=allow

# Initialize and verify:
serena init

After that, serena --help should work. To switch to the JetBrains backend:

serena init -b JetBrains

Connecting to Claude Code

Add this to your Claude Code MCP config (~/.claude/mcp.json or your project’s .claude/mcp.json):

{
  "mcpServers": {
    "serena": {
      "command": "serena",
      "args": ["mcp", "start", "--project", "${workspaceFolder}"]
    }
  }
}

Restart Claude Code, then run /mcp to confirm serena is listed and its tools are available. You should see entries like find_symbol, find_referencing_symbols, replace_symbol_body, insert_after_symbol, rename, get_symbols_overview, and safe_delete.

Connecting to Codex / OpenCode / Cursor

The same serena mcp start command works for any MCP client. Codex CLI uses ~/.codex/mcp.json, Cursor uses Settings → MCP, OpenCode uses its own mcp.json. Each takes the same command + args pair.

For remote agents or shared infrastructure, run Serena in HTTP mode:

serena mcp start --transport http --host 0.0.0.0 --port 9121 --project /path/to/repo

Then point your client at http://your-host:9121/mcp. This is how teams share one Serena instance across multiple developers’ agents — particularly useful in monorepos where indexing is expensive.

What the Tools Actually Do

Serena exposes ~20 tools. The ones that matter for day-to-day agent work:

Retrieval

• get_symbols_overview(file_path) — returns the top-level structure of a file (classes, functions, exports). The agent does not have to read the whole file to know what is inside.
• find_symbol(name_path) — locates a symbol by qualified path (MyClass/my_method or module.submodule.func). Faster and more precise than grep.
• find_referencing_symbols(name_path) — every place a symbol is actually used, with no false positives from comments or unrelated names.

Editing

• replace_symbol_body(name_path, new_body) — swap a function or class body without ever reading the file in full. The agent specifies the symbol and the new code; Serena and the LSP handle the edit.
• insert_after_symbol / insert_before_symbol — add new methods next to existing ones, atomically.
• safe_delete(name_path) — delete only when no references remain. Refuses unsafe deletes by default.

Refactoring

• rename(name_path, new_name) — LSP-driven rename across the whole project. With JetBrains, this also updates string references in templates and configs that match the symbol.

Memory

Serena ships a built-in memory system: write_memory, read_memory, list_memories. Stored as project-local files. Many users combine this with AGENTS.md / CLAUDE.md, but it is opt-in — disable it with one config line if you prefer your harness’s native memory.

A Real Example: Renaming a Method Across a TypeScript Monorepo

Without Serena, here is the abridged Claude Code transcript when I asked it to rename fetchUser to getUserProfile across a 30-file Next.js + Prisma codebase:

[Read app/api/users/route.ts]
[Read lib/db/users.ts]
[Read lib/db/users.test.ts]
[Read components/UserCard.tsx]
... [11 more reads] ...
[Edit lib/db/users.ts]
[Edit app/api/users/route.ts]
[Bash: pnpm tsc --noEmit]
[Errors: 6 unresolved references]
[Read app/users/[id]/page.tsx]
[Edit app/users/[id]/page.tsx]
[Bash: pnpm tsc --noEmit]
[Errors: 2 unresolved references]
... eventually green after ~38K tokens

With Serena attached, the same task:

[serena.find_symbol(name_path="fetchUser")]
  → ts-language-server returns canonical location: lib/db/users.ts:42
[serena.find_referencing_symbols(name_path="fetchUser")]
  → 14 references across 9 files
[serena.rename(name_path="fetchUser", new_name="getUserProfile")]
  → atomic, 14 edits committed in one operation
[Bash: pnpm tsc --noEmit]
  → clean

Roughly 4K tokens, one shot, no hallucinated edits. That ratio is what is driving the adoption.

Configuration and the 40-Language Promise

Serena has a multi-layer config system: global (~/.serena/serena_config.yml), MCP launch flags, per-project (.serena/project.yml), context profiles (agent, ide-assistant, desktop-app), and composable modes (editing, planning, interactive).

The default agent context disables read_file, search_for_pattern, and execute_shell_command because Claude Code already provides those. Only the unique Serena tools (symbol-level retrieval, refactor, memory) are exposed — avoiding tool-name collisions. If you want everything on, run serena mcp start --context full --mode editing,planning.

The 40+ language claim is real but conditional. Serena ships glue for 40+ language servers; most have to be installed independently. Trivial setups: Python (pyright), TypeScript (typescript-language-server), Rust (rust-analyzer), Go (gopls), and the usual JSON/YAML/Markdown crew. Expect 5–10 minutes of setup for Java/Kotlin (jdtls), C/C++ (clangd needs compile_commands.json), Swift (sourcekit-lsp, macOS-friendly), C# (Roslyn variants more reliable), and the community LSPs (Elixir, Elm, Haskell). Serena reports missing servers on serena init and points you at the install command — it does not silently fall back to grep.

Community Reactions

Sampling the high-engagement threads on r/ClaudeAI, r/ChatGPTCoding, r/LocalLLaMA, and r/mcp:

• r/ClaudeAI — “Try out Serena MCP. Thank me later” — top comments note Serena replaces the need for a separate indexer; HTTP/SSE mode is supported.
• r/ClaudeAI — “Claude and Serena MCP - a dream team for coding” — practitioner gripe: “I give Claude the URL and 25% of the time it can get Serena working. 75% it takes some finagling.” This is the install-friction issue the maintainers fight with their no-marketplace warning.
• r/LocalLLaMA — “Fully Featured AI Coding Agent as MCP Server” — focus on Serena replacing RAG entirely. The maintainer argues LSP-based retrieval is strictly better than vector search for code, because it returns canonical references, not approximate matches.
• r/mcp — debate about whether Serena is “an agent” (it isn’t — it’s tooling for agents). Maintainer: “Serena is more like Cursor Agent or Claude Code, just way cheaper, in some situations better.”

Recurring themes: install friction is real, the value when it works is high, and the gap between “agent without Serena” and “agent with Serena” is most visible in large codebases (>50K LOC).

Honest Limitations

Things Serena does not do well, that you should know before adopting:

• First-time setup is fiddly if you have rare language servers or a non-standard repo layout. Plan 30 minutes for the first project.
• Refactor coverage is uneven across LSPs. move, inline, and propagate deletions only exist in the JetBrains backend — the free LSP backend covers rename, replace_symbol_body, insert_*, and safe_delete but not the deeper structural refactors.
• No interactive debugging in the LSP backend. Setting breakpoints, stepping through code, evaluating expressions — JetBrains plugin only.
• Indexing cost. On a fresh checkout, language servers index from scratch. For a large monorepo this can be several minutes; agents calling Serena during this window get slower responses or empty results.
• Memory system is simple. It is project-local files, not a vector store, not auto-summarized. If you want fancy episodic memory, layer it yourself or use your harness’s memory.
• Not a chat interface. Serena does not generate code on its own. You still need an LLM with tool-calling. Serena is the toolkit, not the brain.

Serena vs. The Alternatives

Tool	Approach	Strength	Weakness
Serena (LSP)	LSP-backed MCP server	Free, 40+ languages, symbol-precise	Some refactors LSP-only
Serena (JetBrains)	IDE plugin + MCP	Full IntelliJ refactor power	Paid, JetBrains required
Cursor built-in semantic	Embedding-based search	Zero setup	Approximate, not symbolic
Aider’s repo map	Tree-sitter + ranking	Lightweight, language-agnostic	No edits, no refactor
Cline / Roo with grep	Pure regex / file read	Zero setup	Token-heavy, fragile

Serena’s niche: open-source, multi-language, IDE-grade precision, MCP-native. Use Serena when your codebase is >20K LOC, you need cross-file refactors, you want deterministic symbol matches, and you want to cut context bloat 2–5x. Skip Serena when the repo is tiny, when you’re scaffolding greenfield code, or when your language has no decent LSP.

FAQ

Is Serena an AI coding agent? No. Serena is an MCP server that exposes IDE-grade tools to coding agents. You still need Claude Code, Codex, Cursor, or another MCP-speaking client to do the actual work. Serena makes that client smarter and more efficient.

Does Serena cost anything? The core Serena project is MIT-licensed and free. The optional JetBrains plugin is paid (free trial available) and unlocks IntelliJ-grade refactoring like move and inline. The free LSP backend covers most workflows.

Can I run Serena on a remote server and share it across my team? Yes. serena mcp start --transport http --host 0.0.0.0 --port 9121 exposes an HTTP MCP endpoint. Each developer points their MCP client at the URL. This is also the recommended setup for CI/CD agents that share a pre-indexed monorepo.

Does Serena work with local models (Ollama, vLLM, llama.cpp)? It works with any client that speaks MCP. If your local-model harness supports MCP (OpenWebUI, LibreChat, MindsDB), Serena plugs in. If your harness is custom, MCP is a relatively small protocol to implement.

Why not just use embeddings for code search? Embeddings are approximate; LSP is exact. For “find every caller of User.delete” you want a deterministic answer including all 23 call sites with no false positives, not a top-K similarity search. Embedding search is great for “find code similar to this fuzzy idea.” For navigation and refactoring, symbolic > semantic-similarity.

How does Serena compare to Cursor’s built-in indexing? Cursor’s index is embedding-based and proprietary; great inside Cursor, invisible outside. Serena is symbolic, open-source, and works in any MCP client. They solve different problems and can be used together — Cursor for “find similar code,” Serena for “rename this symbol everywhere.”

Verdict

If you are running Claude Code, Codex, or any MCP-capable agent on a real codebase — not a toy app — Serena is one of the highest-leverage MCP servers available right now. The 24K-star momentum is earned: it solves a concrete pain (token-inefficient code navigation), it does so with deterministic guarantees that embeddings cannot match, and it is free and open under MIT.

The install friction is the main thing keeping this from being a no-brainer. Plan a 30-minute setup window per project, use the official uv tool install path (not marketplaces), and validate with /mcp in your client before trusting it on important work.

For solo developers, Serena will save you obvious tokens and obvious time. For teams running shared agent infrastructure, Serena over HTTP transport is currently the cleanest way to give every agent a real IDE — without paying per-seat for a closed-source IDE plugin.

The agents themselves keep saying it. Listen to them.