What Is Serena MCP? Code Search and Editing Tools for Claude Code and Codex, Setup and Security
You connect Serena to a coding assistant (such as Claude Code or Codex); the assistant then gets code-editor tools like "where is this function, where is it used, rename this everywhere", and in a large project it goes straight to the relevant function instead of reading files from top to bottom. It is open-source software; the software is free, the real work is done by the model of the assistant you connect, and that assistant's plan applies. It has no use for someone who doesn't write code; you install it from the terminal with uv, and it needs no account or key. Because it can change files and run shell commands, read the security section.
- What it does
- Gives a coding assistant symbol lookup and rename tools
- Type
- MCP server (runs on your computer)
- Where
- Claude Code, Claude Desktop, Codex, VS Code, JetBrains
- Requirements
- uv and a terminal; no account or key
- Caution
- Can change files and run shell commands
- Latest version
- 2.0.0 (13.10.2026)
- Cost
- Free, open source
What is Serena used for?
MCP is a common standard that lets AI apps connect to outside tools. Serena is a small program built on that standard: it gives a coding assistant tools to navigate and change code the way an editor understands it (at the level of functions, classes and variables). To understand code it uses the language servers that editors use; it supports more than 40 languages (README).
Can change files and run shell commands.
Who it suits: developers who work on a large codebase with an assistant like Claude Code or Codex and are frustrated that the assistant edits the wrong place or burns through usage by reading too much. Who it doesn't suit: people who don't write code; Serena is not AI, it doesn't produce answers on its own, and the work is done by the model of the assistant you connect.
Serena changes your files. Always keep the project under version control (git); the official docs recommend this too.
How do you install Serena?
Installation is done from the terminal. The only hard requirement is uv (a Python package tool); uv installs Python for you. The commands below are taken verbatim from the official README and docs.
- Install uv: docs.astral.sh/uv/getting-started/installation
- Install Serena and run the initial setup (the two commands below).
› uv tool install -p 3.13 serena-agent› serena init!The README's own warning: don't install Serena from an MCP or plugin marketplace; the commands there are outdated. Use the uv route above.
› serena setup claude-code› claude mcp add --scope user serena -- serena start-mcp-server --context claude-code --project-from-cwd- Check that it's installed by typing
/mcpin Claude Code. - If Serena starts slowly, the docs recommend raising MCP_TIMEOUT (for example to 60000).
- Open claude_desktop_config.json via File › Settings then Developer then MCP Servers then Edit Config.
- Add this block:
{ "mcpServers": { "serena": { "command": "serena", "args": ["start-mcp-server", "--context=desktop-app"] } } } - Save; fully quit the app with File › Exit and reopen it (closing the window normally only minimizes it).
- You need to activate the project in every chat: "Activate the current dir as project using serena".
› serena setup codexFor manual setup, the docs describe adding a [mcp_servers.serena] block to ~/.codex/config.toml. Because the Codex app doesn't start in the project folder, activating the project at the start of each session is recommended.
- VS Code: from the command palette, choose MCP: Add Server › Command (stdio).
- Enter the command below; the project doesn't activate on its own, so you activate it in each session.
› serena start-mcp-server --context=vscodeThe docs have no separate steps for editors like Cursor, Cline or Windsurf. General guidance: enter the command below as stdio in the client's "add custom MCP server" screen.
› serena start-mcp-server --context ideHow do you use Serena?
Serena runs in the background; you write normal requests to your assistant, and the assistant uses Serena's tools on its own when they fit. The project has to be activated: if Claude Code and Codex are started from the project folder this is automatic; in Claude Desktop and VS Code you type the sentence below at the start of the chat.
!Serena writes changes to your files. Start from a clean point in git and check the result with git diff.
Which apps does Serena work with?
| Claude CodeYes | The official docs have a dedicated setup section (serena setup claude-code). |
|---|---|
| Claude DesktopYes | The official docs give config file steps. |
| Codex (CLI and app)Yes | The official docs have a dedicated section (serena setup codex). |
| VS CodeYes | The official docs have a dedicated section. |
| GitHub Copilot (CLI and JetBrains), Junie, AI AssistantYes | The docs have dedicated sections; also for Grok Build CLI, CodeBuddy and Antigravity. |
| Cursor, Cline, WindsurfUnclear | The docs only mention them by name, with no specific setup steps; the general editor guidance (--context ide) is recommended. |
| ChatGPTUnclear | The docs describe only an indirect route (it requires a custom GPT, a bridge program and a tunnel); not a straightforward setup. |
"Not in the docs" doesn't mean it won't work, only that the official documentation doesn't cover it. This list is compiled from the client sections of the Serena docs.
What can Serena access? Security warnings
Source files in the project (symbols and references via the language server), Serena settings and memory files.
Symbol-level edits and renames in source files; memory files; tools to delete symbols and memories. If a delete or edit goes wrong, git is how you undo it.
The tool list includes a tool that runs commands. It is enabled in the default (Claude Desktop) context and excluded in the Claude Code, Codex and editor contexts. In the new version (2.0), under one interface option these exclusions are not treated as a guarantee; the official security page says the only way to get full protection is an isolated environment (for example Docker).
The official privacy page says no personal or project data is sent out. Still, anonymous usage information is sent on every launch (version, operating system, interface, language, context); SERENA_USAGE_REPORTING=false turns it off. Tool results (including code snippets) go to the model of the assistant you connect.
- New (October 14, 2026): GHSA-pp6p-xvxf-8hhx, high severity. When a malicious repository is opened with Serena, code can be run on your computer through the symbol cache. Versions 1.7.1 and earlier are affected; the fix is 2.0.0. If you're on an older version, update; staying on 1.7.0 for the MIT license leaves this hole open.
- Two advisories were published earlier: CVE-2026-49471 targeting the Dashboard (high; versions before 1.5.2) and template injection in project activation, GHSA-pp25-4cg4-qcr9 (critical; 1.6.1 and earlier).
- The two older ones are fixed in 1.7.0 and later. For 2.0.0, no published advisories appear apart from these three (October 15, 2026). This is not a security certification.
The official docs assume the local machine, the connected assistant and the repository being worked on are trusted. Don't open a repository you don't trust with Serena; the docs say the answer for untrusted repositories is an isolated environment.
!This information is compiled from the official docs and GitHub records; it is not a security audit or certification. Check your team's rules before using it on company code.
Is Serena free? License and version
The Serena software itself is free and open source. The only paid part is the optional JetBrains plugin: its Marketplace listing shows a 7-day trial, and the price is not shown in the official sources. The assistant you connect (Claude, Codex, etc.) has its own plan and limits on top.
| Version | License |
|---|---|
| 2.0.0 and later (latest version 2.0.0, October 13, 2026) | GPL-3.0-or-later (its bundled SolidLSP component is MIT) |
| 1.7.0 and earlier | MIT; 1.7.0 is the last MIT version. Caution: 1.7.1 and earlier have a high-severity remote code execution vulnerability (GHSA-pp6p-xvxf-8hhx), fixed only in version 2.0.0 |
The official command doesn't pin a version: a new install gets the latest version (currently 2.0.0). The official sources state no separate restriction on commercial use; how the GPL terms affect your own work requires legal advice, and this page is not legal advice.
Common issues and fixes
| What happens | What to do |
|---|---|
| The assistant can't connect to Serena, or the "serena" command isn't found | If Serena starts slowly, raise MCP_TIMEOUT. If the client can't find serena, put the full path to serena in the config (Claude Desktop doesn't inherit shell settings). |
| Serena looks installed but the assistant doesn't use its tools | The official docs attribute this to Claude Code's tool-loading behavior and describe an optional (alpha) hook setup and a system prompt option. Starting your request with "Using Serena…" also helps steer it. |
| The Serena dashboard window opens on every launch | Set web_dashboard_open_on_launch: False in the global config, or start the server with --open-web-dashboard False. |
| Very slow or stuck on first use | In large projects, build the cache in advance with serena project index; check the language prerequisites (Java, C#, Go, etc.) on the "Language Support" page of the docs. |
| Reported by users Memory and CPU fill up, and many serena processes show up | Reported in many GitHub issues; the official sources give no single fix. Close servers you aren't using, and if it continues, move to the latest version. |
| Install or language server errors on Windows | The docs recommend the setting git config --global core.autocrlf true. Reported by users There are many Windows-titled issues (npm not found, build tools and similar). |
How do you uninstall Serena?
- Remove it from the client. Claude Code:
claude mcp remove serena. Claude Desktop: delete the serena block from the config file, then quit the app with File › Exit and reopen it. Codex: delete the [mcp_servers.serena] block in ~/.codex/config.toml. - Uninstall the program.
uv tool uninstall serena-agent - Delete leftovers manually (optional). These are not deleted automatically: the .serena folder in your user folder (settings, logs, downloaded language servers) and the .serena/ folder in each project (memories, cache).
Frequently asked questions
What is Serena MCP and what is it used for?
An open-source program that gives coding AI assistants (such as Claude Code or Codex) function- and class-level search, editing and rename tools. MCP is the standard AI apps use to connect to outside tools. The work is still done by the model of the assistant you connect.
How do I install Serena in Claude Code?
First install uv, then run uv tool install -p 3.13 serena-agent and serena init; then type serena setup claude-code. The README says not to install Serena from plugin or MCP marketplaces because the commands there are outdated.
Which apps does Serena work with?
Those with setup steps in the docs: Claude Code, Claude Desktop, Codex, VS Code, GitHub Copilot (CLI and JetBrains), JetBrains Junie and AI Assistant, Grok Build, CodeBuddy, Antigravity. Cursor, Cline and Windsurf are mentioned only by name, with no specific steps.
Is Serena free, and what is its license?
The software is free and open source. 2.0.0 and later is GPL-3.0-or-later, 1.7.0 and earlier is MIT. The only paid item is the optional JetBrains plugin; the plan of the assistant you connect applies separately.
Related guides
Sources
- Serena README
- Serena docs: client setup
- Serena docs: tools
- Serena docs: security
- Serena docs: privacy
- License (LICENSE)
- PyPI: serena-agent
- GitHub security advisories
- GitHub releases
Not clear in the official sources: Price of the JetBrains plugin (unclear in the official sources) · what the interface option is for new installs with 2.0 (the docs don't say explicitly) · menu paths for Cursor, Cline and Windsurf · a Turkish option in the Serena dashboard (not stated in the official sources). Each is covered in its section with what you can do.