Skip to content
MCP Shelf

Pod to App: Claude Code

How to install Serena in Claude Code

By Sophie Filer · Updated 11 Nov 2026 · Steps checked against Serena's own docs on 11 Nov 2026

The short answer

Install Serena with uv tool install -p 3.13 serena-agent, run serena init, then serena setup claude-code. Serena then gives Claude Code symbol-level search, rename and edit tools backed by a language server.

Terminal
uv tool install -p 3.13 serena-agent
serena init
serena setup claude-code
Needs
uv
Languages
40+ via language servers
Sign-in
None
Price
Free; JetBrains plugin paid

Install it step by step

  1. Step 1: Install uv, then Serena: uv tool install -p 3.13 serena-agent. The serena command should now work in your shell.
  2. Step 2: Run serena init to set it up with the free language-server backend and check everything works.
  3. Step 3: Run serena setup claude-code to connect it to Claude Code.
  4. Step 4: Start Claude Code, run /mcp, and reconnect serena if it shows as not ready.
  5. Step 5: Ask: "Use Serena to find every caller of createOrder and rename it to placeOrder."

Add it by hand: one project or all of them

ScopeCommand
Every projectclaude mcp add --scope user serena -- serena start-mcp-server --context claude-code --project-from-cwd
This project onlyclaude mcp add serena -- serena start-mcp-server --context claude-code --project "$(pwd)"

The claude-code context matters: it turns off Serena's basic file and shell tools that Claude Code already has, so the two do not compete.

Add the hooks so Claude Code keeps using it

Serena's docs are frank: recent Claude Code versions often forget Serena's tools and drift back to grep and file reads. Their fix is a set of optional hooks. Add them to .claude/settings.json in the project, or ~/.claude/settings.json for everything:

.claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      { "matcher": "", "hooks": [{ "type": "command", "command": "serena-hooks remind --client=claude-code" }] },
      { "matcher": "mcp__serena__*", "hooks": [{ "type": "command", "command": "serena-hooks auto-approve --client=claude-code" }] }
    ],
    "SessionStart": [
      { "matcher": "", "hooks": [{ "type": "command", "command": "serena-hooks activate --client=claude-code" }] }
    ],
    "SessionEnd": [
      { "matcher": "", "hooks": [{ "type": "command", "command": "serena-hooks cleanup --client=claude-code" }] }
    ]
  }
}
  • remind nudges Claude Code toward Serena after several grep or file-read calls in a row.
  • activate asks it to activate the project and read Serena's instructions when a session starts.
  • auto-approve approves Serena's tools when you are already in a permissive mode, instead of prompting every time.
  • cleanup tidies session data at the end. Include only the hooks you want.

If it does not work

What you seeWhat to do
serena times out on startBig projects take time to index. Set export MCP_TIMEOUT=60000 in your shell profile.
Command serena not found by Claude CodeUse the full path to the serena executable in the add command.
Connected, but Claude Code ignores itAdd the hooks above. Serena also offers a system prompt override: claude --system-prompt="$(serena prompts print-cc-system-prompt-override)".
A language is not understoodSome languages need extra language-server dependencies; see Serena's language support page.

MCP Shelf take

Is Serena worth adding to Claude Code?

Serena makes the biggest difference on large codebases, where Claude Code would otherwise grep, read whole files and edit by text matching. With Serena it can jump to a symbol, find real references and rename across files in one step. It is not a no-brainer, though: setup takes a few commands, and you need the hooks or Claude Code tends to forget it exists. On a small project you may not notice it. On a big one in a typed language, it is one of the most useful servers on the shelf.

Sophie Filer

Questions

Is Serena free?

Yes, with the default language-server backend. The optional JetBrains plugin backend is paid, with a free trial, and adds things like moving files and type hierarchy.

Why does Claude Code not use Serena's tools?

Claude Code leans toward its own built-in tools. Serena provides hooks that remind it and activate the project, plus an optional system prompt override.

Should I install Serena from a marketplace?

No. Serena says marketplace entries carry outdated install commands. Install with uv and run serena setup claude-code.

Sources: the steps on this page are written in our own words from Serena's own install docs, the README, the README. If they disagree with this page, the project's docs win; please tell us from the server page.