Serena MCP Server for Claude

Content

Serena turns Claude into a coding agent that works at the level of symbols rather than raw text. Instead of pasting entire files into context, Serena uses language servers to find symbols, trace where they are referenced, and apply precise edits to the right definition. That keeps context focused, reduces the chance of broad and risky rewrites, and lets Claude navigate a real codebase the way an IDE does. It is open source and free, and it works across the languages its underlying language servers support.

Features

• Semantic, symbol-level code retrieval backed by language servers rather than plain text search.
• Find symbols and the places that reference them to understand impact before changing code.
• Apply targeted edits to a specific symbol or definition instead of rewriting whole files.
• Keeps model context focused by pulling in only the relevant code, not entire files.
• Works across many programming languages through the language servers it integrates.
• Open source under an MIT license and runs locally as a standard MCP server.

Use Cases

• Navigate an unfamiliar codebase by jumping between symbols and their references.
• Perform focused refactors that touch a single definition and its call sites.
• Investigate the blast radius of a change before applying it.
• Let Claude make precise, reviewable edits in a real project under version control.
• Reduce context bloat on large repositories by retrieving only relevant code.

Installation

Claude Code

1. Install the uv toolchain (provides uvx) from https://docs.astral.sh/uv.
2. Run: claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context ide-assistant
3. Verify the server is registered: claude mcp list
4. Open a project and ask Claude to find a symbol to confirm Serena is active.

Claude Desktop

1. Install the uv toolchain so uvx is available on your PATH.
2. Open your Claude Desktop configuration file.
3. Add the Serena server to the mcpServers section using the configuration below.
4. Restart Claude Desktop and confirm the server appears.

Configuration

{
  "serena": {
    "command": "uvx",
    "args": [
      "--from",
      "git+https://github.com/oraios/serena",
      "serena",
      "start-mcp-server",
      "--context",
      "ide-assistant"
    ]
  }
}

Examples

Navigate to a symbol

Ask Claude to locate a definition instead of searching text.

"Find the definition of the AuthService class and show me its methods."

Trace references before refactoring

Understand impact before changing a function.

"Find everywhere that calls parseConfig so I can see what a signature change would affect."

Apply a focused edit

Let Serena change a single definition rather than a whole file.

"Update the body of the validateToken function to add an expiry check, and leave the rest of the file unchanged."

Security

• Serena can read and modify files in the project you target, including applying code edits, so only run it on codebases you control and can review.
• Run it against a version-controlled working tree so automated changes show up in diffs and can be reverted.
• Depending on configuration it may start language servers or run project commands; enable it only on trusted projects.
• Do not point it at directories holding secrets or private data you do not want read into the model context.

Troubleshooting

uvx is not found

Install the uv toolchain from https://docs.astral.sh/uv and confirm uvx --version works. uvx is required because Serena is distributed as a Python project rather than an npm package.

First run is slow or fails to fetch Serena

The initial launch resolves Serena from its Git repository, which needs internet access and a working uv cache. Retry once the network is available; subsequent runs reuse the cached install.

Language features or symbol lookups do not work

Serena relies on language servers for the project's language. Make sure the project is one Serena can index and that any required language tooling is available in the environment.

Server not listed in Claude Code

Re-run the claude mcp add serena ... command, then claude mcp list. Confirm it was added to the scope (project versus user) you are running in, and that the working directory points at the project you want to analyze.

• Source repositorygithub.com 2026-07-18T11:38:32+00:00
• Documentationgithub.com
• Submitted by glorydavid030232026-06-03