Serena MCP Setup Guide: Claude Code, Codex, and JetBrains (2026)¶

For / Key Points

For: Developers who want symbol search, reference tracking, and semantic refactoring in large repositories used with Claude Code or Codex

Key Points:

Serena is not a standalone AI agent; it adds IDE-like semantic tools to an MCP client
The current installation path is uv tool install -p 3.13 serena-agent followed by serena init
Use the dedicated setup commands for Claude Code and Codex, then verify MCP connection and project activation

What Serena adds¶

Serena uses language servers or its JetBrains plugin to understand code symbols and expose retrieval, editing, and refactoring tools through MCP.¹

Text search answers “where does this string occur?” Serena can answer questions such as:

Where is this class or function defined?
Which symbols reference this function?
Can the body of this symbol be replaced without line-based surgery?
Can a symbol be renamed across references?
Can the agent navigate another project or a dependency definition?

Built-in search and editing may be faster for a one-file change. Serena becomes more useful in monorepos, reference-heavy changes, symbol-level exploration, and multi-language repositories.

Current prerequisites and release state¶

The older uvx --from git+https://... examples are no longer the recommended installation. Serena is released as a v1 package on PyPI, and its Quick Start uses uv tool.²

The latest release on July 16, 2026 was v1.6.0. The README lists more than 40 languages for the LSP backend, including Python, TypeScript, Java, Go, Rust, C/C++, Swift, Kotlin, Dart, JSON, and YAML.³¹

Some languages require an additional runtime or language server. A listed language does not imply that every semantic operation has identical capability.

1. Install uv and Serena¶

Confirm uv is available:

uv --version

Install uv from Astral's official instructions if needed, then install and initialize Serena:

uv tool install -p 3.13 serena-agent
serena --version
serena init

serena init uses the LSP backend by default. After installing the paid Serena JetBrains Plugin, initialize that backend with:²

serena init -b JetBrains

Upgrade through uv tool:

uv tool upgrade serena-agent
serena --version

The official README warns that MCP or plugin marketplaces may carry outdated startup commands. Use the project Quick Start rather than copying a marketplace command.¹

2. Connect Claude Code¶

The shortest setup is:

serena setup claude-code

For a manual user-level registration that derives the project from the current working directory:

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

To register Serena only in the current repository:

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

Restart Claude Code, open /mcp, and verify that serena is connected. Then ask:

Activate the current project with Serena and read the initial instructions.
List the major symbols without changing the repository.

Serena's current client documentation notes that some recent Claude Code and model versions prefer built-in tools and may not invoke Serena. Only if you reproduce that behavior, consider the documented system-prompt override or optional Serena hooks. The hooks are marked alpha.⁴

3. Connect Codex CLI or App¶

Run the dedicated setup:

serena setup codex

The equivalent manual ~/.codex/config.toml entry is:⁴

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

Restart Codex and verify the server with /mcp. A Codex App session may not start in the repository directory, so begin with:

Activate the current directory as a Serena project and read the initial instructions.

4. Connect a JetBrains client¶

There are two paths:

Use the free LSP backend through MCP with Copilot, Junie, or JetBrains AI Assistant
Use the paid Serena JetBrains Plugin backend for IDE analysis, refactoring, and debugging capabilities

For GitHub Copilot in JetBrains, the current MCP example is:⁴

{
  "servers": {
    "serena": {
      "type": "stdio",
      "command": "serena",
      "args": [
        "start-mcp-server",
        "--context=jb-copilot-plugin"
      ]
    }
  }
}

Junie and JetBrains AI Assistant use different recommended contexts. Copy the current example for the exact client from Serena's client page. Do not register the same server at both global and project scope unless the client documentation explicitly calls for it.

5. Verify the project, not only the connection¶

MCP connection alone does not prove semantic analysis works. Check in this order:

The MCP client reports Serena as connected
The current repository activates successfully
A symbol overview succeeds for a known source file
Symbol search finds a known class or function
Reference search returns expected callers
A final Git status shows that read-only checks created no diff

Test edits only in a disposable branch after the read-only path works.

6. Use Serena where semantics matter¶

Work	Serena	Built-in tools
Explore symbols and references	First choice	Supporting role
Replace a function or class body	First choice	Fine for tiny edits
Rename across files	First choice when the language supports it	Avoid raw string replacement
Small README or configuration edit	Often unnecessary	First choice
Regex search through logs or arbitrary text	Depends	`rg` is often faster

Serena's basic tools overlap with Claude Code and Codex. Recommended contexts disable some duplicates. Minimizing overlap often improves tool selection and context use more than exposing every possible tool.

Troubleshooting¶

The client cannot find `serena`¶

A GUI client may not inherit your interactive shell PATH.

which serena
uv tool dir --bin

Use the absolute executable path in the MCP entry and restart the client.

MCP connects but the agent does not use Serena¶

Confirm the --context matches the client
Explicitly activate the project and read initial instructions
Reduce overlapping built-in and Serena tools
For Claude Code, try documented overrides or hooks only after reproducing the issue

Symbol analysis fails¶

Check the language-specific prerequisites in Serena's Language Support page
Install repository dependencies before analysis
Inspect Serena logs or dashboard for language-server startup failures
In monorepos, confirm the active project and additional workspace folders

Security and operations¶

Serena can read and edit code and, depending on configuration, execute shell commands. Use the trusted official distribution and apply normal coding-agent controls:

Start with read-only operations
Work inside a Git-controlled tree
Review destructive tools before enabling auto-approval hooks
Put authentication and network boundaries around any externally reachable HTTP/SSE server
Review repository-level Serena configuration as code

Summary¶

The current setup is no longer the old pattern of launching GitHub main through uvx:

uv tool install -p 3.13 serena-agent
serena init
serena setup claude-code   # or: serena setup codex

After connecting, validate project activation, symbol overview, known-symbol lookup, and references in read-only mode. Reserve Serena for changes where semantic structure adds value instead of routing every edit through it.