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 consumed, 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.
One detail most guides skip: 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 ships with evaluation prompts that let you benchmark Serena against built-in agent tools on real codebases, which is unusual transparency for an MCP server.
See Serena on MCPVault for grades, tools and install details.
Language Server vs JetBrains Plugin: Which Backend?
Most posts about Serena only mention the language server backend. That is the free default, but 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.
Claude Code Hooks: The Setup Most Guides Miss
Here is the information gain angle most SERP results skip entirely. 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 these hooks, many users report that Claude Code simply forgets Serena exists after the first few exchanges. VS Code users can set up similar hooks in ~/.copilot/hooks/serena-hooks.json.
Frequently Asked Questions
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 is what 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.