Serena MCP: the IDE for your agent

Serena is an MCP toolkit that gives a coding agent IDE-style tools: find a symbol, list who references it, rename it, replace its body, all without reading whole files. It supports more than 40 languages through open-source language servers, plus a paid JetBrains plugin backend. The app is GPL-3.0-or-later. We checked the README and docs on 31 October 2026.

Quick facts

The GitHub API reports the licence as "NOASSERTION" because the repo has two licences. The README is the authoritative text, and it says the split above. If you plan to bundle Serena inside a product, read the licence page and ask your legal team.

What it lets an agent do

Most coding agents explore code the blunt way. They grep, open a whole file, scroll, then edit by line number or by pattern. That burns tokens and breaks on large files.

Serena changes the unit of work from lines to symbols: functions, classes, methods. It uses the same language server protocol that powers autocomplete and "go to definition" in an editor. The README calls its tool design "agent-first": high-level actions rather than low-level line numbers and search patterns.

In practice, an agent can:

• ask for the outline of a file without reading the body;
• find a symbol by name across a project;
• list every place that references it;
• rename it everywhere in one call;
• replace just that function's body, or insert code right before or after it;
• keep notes in a memory system that survives between sessions.

The README's claim is that this makes agents faster, more efficient and more reliable, especially on large codebases. The page includes self-evaluations written by AI agents. They are the maintainers' own exercise, not an independent benchmark, so we do not repeat the numbers or quotes.

Tools and capabilities

Straight from the README feature tables. "LS" means the language server backend. "JB" means the JetBrains plugin.

Retrieval

Refactoring

Symbolic editing: replace symbol body, insert after symbol, insert before symbol and safe delete work in both backends.

Debugging: exclusive to the JetBrains plugin. The README describes breakpoints, variable inspection, expression evaluation and execution control through a REPL-style interface.

Basic utilities: search_for_pattern, replace_content, list_dir, find_file, read_file and execute_shell_command. The README says these are typically disabled when Serena runs inside a harness such as Claude Code or Codex, since the harness already provides them.

Memory: a simple memory system for long-lived workflows. Some users combine it with their agent's own system, such as AGENTS.md. It can be switched off.

Configuration: YAML at several levels: global, MCP launch command, per project with local overrides, per client context, and composable "modes". The README also announces a Serena v2 with a REPL-based agent interface, with a link to the docs for details.

Install it

The README starts with a warning that matters: do not install Serena through an MCP or plugin marketplace, because those listings carry outdated and suboptimal install commands. Install it yourself with uv.

uv tool install -p 3.13 serena-agent
serena init

After the first command, serena should be on your path. serena init sets up the language server backend and checks that things work. Add -b JetBrains to use the JetBrains backend instead. Some languages need extra tools for their language server; the Language Support page lists them.

Then connect your client. There are two ideas to understand first.

Per-workspace clients vs global clients. Claude Code and VS Code keep MCP config per workspace. Codex and Claude Desktop keep it globally. In a per-workspace setup, start Serena with --project <path> and a single-project context. In a global setup you ask the agent to activate the project, for example "Activate the current dir as project using serena". The activate_project tool is needed for that.

Contexts. A context tells Serena which tools to switch off because the client already has them. The docs use claude-code, codex, vscode, copilot-cli and a generic ide context.

Claude Code

The docs offer a helper:

serena setup claude-code

Or add it yourself. For all projects, use the user scope and let Serena find the project from the current directory:

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

For one project only:

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

Check with /mcp. If Serena is slow to start, the docs say to set MCP_TIMEOUT to a larger value, for example export MCP_TIMEOUT=60000. The page also describes hooks that remind Claude Code to use Serena's tools when the client does not pick them.

Codex

serena setup codex

Or put this in ~/.codex/config.toml:

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

The docs say the Codex app does not start a session in the project directory, so ask it to activate the current directory as a project at the start of each session. They also describe optional Codex hooks via serena-hooks, which need a recent Codex version for some events.

VS Code

Run MCP: Add Server, pick Command (stdio), then enter one of these:

• Global (recommended by the docs): serena start-mcp-server --context=vscode
• Workspace: serena start-mcp-server --context=vscode --project ${workspaceFolder}

The docs state that in the global setting a VS Code bug stops Serena from activating the project automatically, so you must prompt "Activate the current dir as project using serena" each session. The workspace setting avoids that, at the price of adding Serena to every project.

Cursor and other IDE clients

The docs treat Cursor with Cline, Roo Code and Windsurf as MCP-enabled IDEs. Add a server whose command is serena and whose args include start-mcp-server and --context ide. The ide context reduces tool duplication. A typical mcp.json entry in Cursor's mcpServers format would be:

{
  "mcpServers": {
    "serena": {
      "command": "serena",
      "args": ["start-mcp-server", "--context", "ide", "--project-from-cwd"]
    }
  }
}

The docs give no Cursor-specific snippet, so treat that block as our adaptation of the generic instruction. Add --project-from-cwd only if your client starts the server in the project directory.

Gemini CLI

The docs list Gemini CLI among terminal clients and suggest --context ide. Add it to ~/.gemini/settings.json using the same command and args:

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

Again, this is the generic recipe applied to Gemini CLI's format, not a block copied from Serena's page. With no project flag, ask the agent to activate the project.

HTTP mode

If your client prefers a URL, start the Serena MCP server in HTTP mode yourself and point the client at the endpoint. The docs give this as the alternative to a launch command: run serena start-mcp-server --transport streamable-http --port 9121, then connect the client to http://localhost:9121/mcp. Only localhost connections are allowed unless you pass --host.

Compatibility at a glance

The docs also cover Copilot CLI, Claude Desktop, JetBrains Junie and AI Assistant, Antigravity, CodeBuddy and ZCode, and mention local GUIs such as Jan, OpenWebUI and Agno.

Real tasks with copy-ready prompts

Learn a module cheaply

Use Serena to get the symbol overview of src/billing/invoice.py.
Tell me what each class does from the names and signatures. Do not
read the function bodies yet.

Rename safely

Rename the function calc_total to compute_invoice_total using Serena's
rename tool. Then list every file it touched.

Find all callers before a change

Find every symbol that references PaymentGateway.charge. Group them by
module and tell me which ones pass the retry argument.

Edit one function only

Use Serena to replace the body of parse_config so it also accepts a
YAML file. Keep the signature. Do not touch other symbols.

Start a session

Activate the current dir as project using serena. Then show me the
available memories.

If your agent ignores the tools, say "use Serena's symbol tools" in the prompt, or add that line to your rule file. See our CLAUDE.md starter template for where it goes.

Security and permissions

Serena has no account and no API key. It runs on your machine and talks to local language servers. That is a good starting point, and it also means the permissions are yours to set.

• It edits your code. Symbol edits and rename write to disk. Use version control and review diffs.
• Shell execution. execute_shell_command exists. The README says it is typically disabled inside harnesses. If you run Serena in a client without its own shell, think about whether you want that tool on. Tool selection is done through Serena's configuration, and the docs recommend that over disabling tools in the client, because Serena's prompts adjust to the enabled set.
• Language servers are programs. Each one is third-party code that runs locally and parses your repo. They are generally open source, but you install and trust them.
• Memory files. Notes Serena stores can contain details of your project. Check where they live before you commit anything.
• Licence. GPL-3.0-or-later applies to the app. Using it as a tool on your own code is different from shipping it. Companies embedding it in a product should check with counsel.

Limits and known issues

• Setup is heavier than most servers. You need uv, and some languages need extra installs. Plan for ten minutes, not one.
• The language server backend is narrower than the JetBrains one. Rename covers symbols only, and move, inline and unused-code removal are JetBrains only. Find declaration does not generally work for external dependencies.
• Quality follows the language server. Serena inherits whatever a language server can do. The tracker shows language-specific reports, such as an F# language server regression (#1209), an Ansible hover failure on Windows (#1182) and a Kotlin hover gap (#924).
• Tools may not get used. The docs list this as a common pitfall and say it is mainly down to client tool discovery. Hooks for Claude Code and VS Code exist to nudge the agent.
• Environment variables. Some language servers need variables, and some clients such as Claude Desktop do not pass shell profile variables to the server process. Put them in the server entry's env.
• PATH problems. If a client cannot find serena, use the full path to the executable.
• A project must be active. Global-config clients need an explicit activation step.
• JetBrains support has gaps. Rider and CLion are unsupported by the plugin, per the README.

Alternatives

Serena complements retrieval servers rather than replacing them. It is about your code. Context7 is about other people's. Compare them in the MCP servers hub.

Which agents it works best with

Serena says its tools shine most in "larger and more complex codebases", and the contexts it ships suggest where it is best supported: Claude Code and Codex have a one-line serena setup helper and hooks. VS Code with Copilot has its own context and a documented workaround for project activation. Cursor and Gemini CLI work through the generic ide context. If your editor is a JetBrains IDE, the paid plugin gives the broadest capability, including refactors the free backend lacks.

Our take

We did not test Serena for this page. This is a reading of the README and docs.

The idea is the right one. Reading a 2,000 line file to change one method is waste, and a text replace across a repo is a gamble. A rename that follows references is a better tool, and agents rarely have one.

What you pay for it is setup and care. You install uv, run a second tool, pick a context, activate a project, and trust language servers. For a small repo, that is more work than it saves. For a large one with many callers, the maths flips.

Two details we like: the README tells you not to use marketplace installs, which is rare candour, and it is open about which features need the paid JetBrains plugin. Two things to watch: the GPL licence for any company use beyond running it as a dev tool, and the fact that the quoted evaluations are self-reported.

Setup checklist

1. Install uv, then run uv tool install -p 3.13 serena-agent.
2. Run serena init and read the success message.
3. Run the serena setup helper for your agent, or add the launch command by hand.
4. Open a session and run /mcp or the equivalent to see the tools.
5. Ask the agent to activate the project, if your client needs it.
6. Try the file outline prompt on a large file.
7. Add one line to your rule file telling the agent to prefer Serena's symbol tools.

Frequently asked questions

What license is Serena under? SolidLSP is MIT and the application is GPL-3.0-or-later. Combined distributions are under the GPL as a whole.

What does Serena need installed? uv, plus extra dependencies for some languages.

Is there a paid option? Yes, the JetBrains plugin backend, with a free trial.

Does it replace my agent's file tools? No. The basic tools are typically disabled in harnesses that already have their own.

Which clients does it work with? Any MCP client. The docs cover Claude Code, Codex, VS Code, Copilot CLI, Claude Desktop, JetBrains tools and more.

*Product names are used descriptively. We are not affiliated with Oraios.*