Serena MCP is an open-source MCP server from oraios that gives a coding agent symbol-level access to a codebase through language servers: find a definition, list every reference, rename across files, and edit inside a function without pasting whole files into context. It runs locally over stdio and works with Claude Code, Claude Desktop, Cursor, VS Code, Windsurf and Codex. See Serena on MCPVault for the grade, tools and install line.
If your AI coding agent treats every file as plain text, it is missing the structure that makes code intelligible. The serena mcp server fixes that. Built by oraios and distributed as serena-agent via uv, Serena gives any MCP-compatible client IDE-level semantic awareness: go-to-definition, find references, safe renames, symbol-level edits, and diagnostics across more than 40 programming languages. With over 28,000 GitHub stars and a Grade A listing on MCPVault, it is one of the most adopted coding toolkits in the MCP ecosystem.
Unlike file-based approaches that flood context with irrelevant lines, Serena operates at the symbol level through Language Server Protocol backends. Your agent asks for a class definition, not a grep result. It renames a method across files without touching unrelated strings. The result is fewer tokens, faster responses, and edits that do not break imports or leave stale references behind.
Installation and Setup
Serena is distributed through uv, the Python package manager from Astral. You need uv installed first:
curl -LsSf https://astral.sh/uv/install.sh | sh
Then install Serena:
uv tool install -p 3.13 serena-agent
After installation, run the initializer:
serena init
This creates a default configuration using the open-source language server backend. If you prefer the JetBrains plugin backend, which adds move, inline, and propagate-deletion refactoring capabilities, initialize with serena init -b JetBrains instead. The JetBrains plugin is paid but offers a free trial.
Claude Desktop and Cursor Configuration
Serena connects to clients through a stdio launch command. For Claude Desktop, add this block to your claude_desktop_config.json:
{
"mcpServers": {
"serena": {
"command": "serena",
"args": [
"start-mcp-server",
"--context=claude-code",
"--project-from-cwd"
]
}
}
}
For Cursor, paste the same command into your ~/.cursor/mcp.json file. VS Code users can run the MCP: Add Server command and enter serena start-mcp-server --context=vscode for global use, or append --project ${workspaceFolder} for workspace-scoped access.
Serena needs project activation before it can resolve symbols. In a per-workspace client like Claude Code, pass --project-from-cwd so the current directory becomes the project automatically. In global clients like Claude Desktop, ask the agent to activate the project on first use with a prompt like "Activate the current directory as a Serena project."
Compatible MCP Clients
| Client | Compatible | Configuration Notes |
|---|---|---|
| Claude Desktop | Yes | Global config, requires project activation |
| Claude Code | Yes | Per-project, --project-from-cwd recommended |
| Cursor | Yes | ~/.cursor/mcp.json or project-level |
| VS Code | Yes | Global or workspace via MCP: Add Server |
| Windsurf | Yes | Same command pattern as Cursor |
| Zed | Partial | Beta MCP support, may need hooks |
| JetBrains IDEs | Yes | Via Copilot plugin or Serena JetBrains plugin |
| ChatGPT | No | Uses GPT Actions, not MCP |
Tools the Server Exposes
Serena exposes two categories of tools: semantic operations powered by LSP, and basic utilities for completeness.
Retrieval tools let your agent explore code without reading entire files. find_symbol locates a definition. find_referencing_symbols finds every call site. symbol_overview returns a file outline. find_declaration and find_implementations navigate inheritance hierarchies. search_in_project_dependencies works only with the JetBrains backend, letting agents trace calls into external libraries.
Refactoring tools perform safe structural edits. rename_symbol renames across the entire codebase. replace_symbol_body, insert_after_symbol, and insert_before_symbol make surgical changes inside a function or class. safe_delete removes unused code. With the JetBrains backend, you also get move (symbol, file, or directory), inline, and propagate_deletions.
Basic utilities include read_file, list_dir, search_for_pattern, replace_content, and execute_shell_command. These are typically disabled when Serena runs inside an agent harness like Claude Code that already provides them, but they remain available for lightweight clients.
Memory management stores long-lived agent context across sessions. You can disable it if you prefer your own system.
Quality Assessment
Serena carries a Grade A on MCPVault with a status of stale. The grade reflects strong maintenance (last updated August 2026), high adoption (28,000+ stars), clear MIT licensing, and extensive documentation at oraios.github.io/serena. The project also ships with evaluation prompts that let you benchmark Serena against built-in agent tools on real codebases.
See Serena on MCPVault for grades, tools and install details.
Language Server vs JetBrains Plugin: Which Backend?
Most posts about Serena mention the language server backend but not why the choice matters.
The language server backend supports 40+ languages through open-source LSP implementations. It covers retrieval, basic refactoring, and symbolic editing. However, cross-file move operations, inline refactoring, and dependency tracing into external libraries require the JetBrains plugin.
The JetBrains plugin uses IntelliJ IDEA, PyCharm, WebStorm, or any supported JetBrains IDE as the analysis engine. It supports every language the IDE supports, which is broader than the LSP list. The tradeoff is cost: the plugin is paid, though a free trial is available.
For most developers, start with the language server backend. Switch to JetBrains only when you need advanced refactoring or work in a language with limited LSP coverage.
Serena not working? The five fixes
1. The project is not activated. Serena is project-based; until a project is active, the symbol tools return nothing useful. In Claude Code, Codex or Gemini CLI start the server with --project-from-cwd, which walks up from the current directory to the nearest folder containing .serena/project.yml or .git and activates it. In Claude Desktop and other global clients, pass --project /path/to/repo or ask the agent to "activate the project at /path/to/repo"; the activate_project tool does the rest.
2. A config drift warning on every update. If you installed Serena through Headroom or another wrapper, you may see "Serena MCP: existing config differs" after each update, because the wrapper changed its recommended launch line (for example from --from git+https://github.com/oraios/serena to --from serena-agent). The wrapper will not rewrite your ~/.claude.json by design. Fix it once: claude mcp remove serena, then re-add with the current command from this page, and the warning stops until the recommendation changes again.
3. The dashboard opens a browser or clashes on a port. Serena starts a web dashboard at http://localhost:24282/dashboard/index.html and opens it by default. Set web_dashboard_open_on_launch: false in ~/.serena/serena_config.yml to stop the auto-open, or web_dashboard_interface to change how it is served. Keep the dashboard itself; it is where you read the logs when a tool call fails.
4. The language server is missing for your language. Serena needs Python 3.13 (uv tool install -p 3.13 serena-agent, then serena init) and installs most language servers on first use. Some languages need a runtime installed first, and the first request in a large repo can take a minute while the index builds. If find_symbol returns nothing in a language that should be supported, open the dashboard logs and look for the language server start line; a missing runtime shows up there.
5. Claude Code ignores the tools. Claude Code prefers its own grep and file tools and drifts away from Serena after a few turns. Start the server with --context=claude-code, which disables the duplicate file tools so the symbolic ones are the only option, and add the two hooks in the section below. If the initial instructions are eating context, add --mode no-onboarding after the first session.
Serena vs Context7 vs built-in grep
| Serena | Context7 | Built-in grep and read | |
|---|---|---|---|
| What it retrieves | Symbols in your code: definitions, references, hierarchies | Current documentation for a library you import | Text matches in files |
| Best for | Refactors and navigation in a large codebase | Writing code against an API you do not remember | Small repos, one-off lookups |
| Token cost | Low: one symbol at a time | Low: only the matching doc sections | High: whole files and grep dumps |
| Setup | uv, Python 3.13, project activation | One npx line, optional free key | None |
| Keep both on? | Yes, with Context7 | Yes, with Serena | Yes, they do not overlap |
Serena and Context7 answer different questions and most Claude Code users run both: Context7 for "how does this library work", Serena for "where is this used in our code".
Claude Code Hooks: The Setup Most Guides Miss
Claude Code and VS Code have a known problem: they bias heavily toward their own built-in tools and often ignore external MCP servers after the first few turns. Serena provides lifecycle hooks that counteract this drift.
For Claude Code, add these hooks to .claude/settings.json (project-level) or ~/.claude/settings.json (global):
{
"hooks": {
"SessionStart": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "serena-hooks activate --client=claude-code"
}
]
}
],
"PreToolUse": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "serena-hooks remind --client=claude-code"
}
]
}
]
}
}
The activate hook prompts the agent to initialize the project at session start. The remind hook nudges the agent back toward Serena's symbolic tools when it makes too many consecutive grep or read_file calls without touching any Serena tools. Without them, Claude Code tends to drift back to its own grep after a few exchanges, which is why the project ships the hooks. VS Code users can set up similar hooks in ~/.copilot/hooks/serena-hooks.json.
Frequently Asked Questions
Why is Serena not working in Claude Code?
The usual causes, in order: the project is not activated (start with --project-from-cwd), the server was added with an outdated launch line (remove and re-add), or Claude Code is ignoring the tools (use --context=claude-code and the hooks above). The dashboard at localhost:24282 shows the logs for anything else.
Does Serena work with Claude Code?
Yes. Claude Code is one of the best-supported clients. Run serena setup claude-code for automatic configuration, or use the manual JSON block above. Serena also provides hooks that counteract Claude Code's bias toward its own built-in tools, which is a common reason agents ignore external MCP servers. Add the hooks to .claude/settings.json as documented in the Serena user guide.
How many programming languages does Serena support?
Over 40 when using the language server backend, including Python, TypeScript, Java, Rust, Go, C++, C#, Ruby, PHP, Swift, Kotlin, and many others. The JetBrains plugin backend supports every language covered by IntelliJ-based IDEs, which is an even broader set.
Can I use Serena without a project directory?
No. Serena is project-based. It needs a root directory to initialize its symbol index. You can activate multiple projects, but each session targets one project at a time. For global clients, use the activate_project tool or prompt the agent to activate the current directory.
What is the difference between Serena and a basic file search tool?
File search returns text matches. Serena returns symbol-aware results: definitions, references, type hierarchies, and safe edit operations. A grep might find "UserService" in a comment; Serena knows which file declares the class, which files import it, and which methods override it. That structural awareness saves tokens and prevents broken refactors. You can read more about how MCPVault assigns quality grades in the grading documentation.
Your server in the vault.
If you built an MCP server, claim the listing and get it in front of developers who are actively looking. Free to claim. Verification is free during early access and earns a do-follow link to your project.
Claim your listing or submit a server if it is not indexed yet.