Serena MCP Guide: Install, Configure, and Use with Claude Code

Serena MCP is an open-source AI coding agent toolkit that runs as an MCP server. It gives Claude Desktop, Claude Code, Codex, and other MCP-compatible clients symbol-level code understanding through the Language Server Protocol (LSP).

If you are searching for serena mcp, install serena mcp, serena mcp config, or how to install Serena MCP in Claude Code, this guide gives you the practical setup path first, then explains advanced usage and troubleshooting.

Serena MCP Quick Start

Use this 5-step quick start if you already have Python tooling installed:

1. Install uv or make sure uvx is available.
2. Start Serena MCP with uvx --from git+https://github.com/oraios/serena serena start-mcp-server.
3. Add Serena MCP to your MCP client config, such as Claude Desktop or Claude Code.
4. Restart the client so it can load the MCP server.
5. Activate your project and let Serena index it before asking for symbol-level edits.

The most common setup mistake is adding the server config but forgetting to restart the client or activate the project.

What Is Serena MCP?

Serena MCP is a coding-agent server designed for codebase-aware editing. Instead of relying only on plain text search or broad RAG-style retrieval, Serena exposes IDE-like tools such as symbol search, reference lookup, and symbol-level insertion.

That makes it useful when you want an AI assistant to:

• understand a large repository without reading every file;
• find classes, functions, and symbols accurately;
• edit code at the symbol level;
• remember project structure between sessions;
• work through Claude Desktop, Claude Code, Codex, Cursor, Cline, Roo-Code, Windsurf, or other MCP clients.

Install Serena MCP

Serena MCP depends on Python tooling. The recommended path is to use uv and uvx because they make Python package execution simpler and more reproducible.

Option 1: Run Serena MCP with uvx Recommended

You can run the latest Serena MCP server directly from GitHub without cloning the repository:

uvx --from git+https://github.com/oraios/serena serena start-mcp-server

This is the simplest command for most first-time users.

Option 2: Clone Serena and Run Locally

If you want to inspect the source code or pin your own local copy:

git clone https://github.com/oraios/serena
cd serena
uv run serena start-mcp-server

If you are running the command outside the install directory, specify the Serena directory explicitly:

uv run --directory /abs/path/to/serena serena start-mcp-server

Option 3: Run Serena MCP with Docker Experimental

Docker can provide isolation and a consistent runtime. Mount your project directory into the container:

docker run --rm -i --network host \
  -v /path/to/your/projects:/workspaces/projects \
  ghcr.io/oraios/serena:latest \
  serena start-mcp-server --transport stdio

Use Docker only if you are comfortable debugging container file paths and network behavior.

Serena MCP Config for Claude Desktop

Claude Desktop is one of the easiest ways to use Serena MCP because it supports MCP server configuration directly.

Claude Desktop Config Example

Open Claude Desktop and go to:

File / Settings / Developer / MCP Servers / Edit Config

Add Serena MCP under mcpServers in claude_desktop_config.json:

{
  "mcpServers": {
    "serena": {
      "command": "/abs/path/to/uvx",
      "args": [
        "--from",
        "git+https://github.com/oraios/serena",
        "serena",
        "start-mcp-server"
      ]
    }
  }
}

After saving the config, fully quit and restart Claude Desktop. A normal window refresh may not reload MCP servers.

Claude Desktop Troubleshooting

If Claude Desktop shows Serena MCP but does not call its tools:

• restart Claude Desktop completely;
• confirm the uvx path is absolute and executable;
• check whether another MCP server exposes conflicting tool names;
• temporarily disable FileSystemMCP or other overlapping file tools;
• open Serena's dashboard/logs to see whether the server actually started.

Serena MCP Config for Claude Code

For Claude Code Serena workflows, add Serena MCP from the project directory you want Claude Code to edit:

claude mcp add serena -- \
  uvx --from git+https://github.com/oraios/serena \
  serena start-mcp-server \
  --context ide-assistant \
  --project $(pwd)

This command does three important things:

1. Registers Serena as an MCP server for Claude Code.
2. Uses the ide-assistant context, which is better suited for code-editing workflows.
3. Points Serena at the current project with --project $(pwd).

After adding the server, restart Claude Code or start a fresh session so the MCP server list is reloaded.

Serena MCP on Windows and WSL2

If you use Claude Desktop on Windows but run Serena inside WSL2, call Serena through wsl.exe in your MCP config.

Example pattern:

{
  "mcpServers": {
    "serena": {
      "command": "wsl.exe",
      "args": [
        "-d",
        "Ubuntu",
        "uvx",
        "--from",
        "git+https://github.com/oraios/serena",
        "serena",
        "start-mcp-server"
      ]
    }
  }
}

Windows users should pay special attention to:

• which environment has uvx installed;
• whether the project path is a Windows path or WSL path;
• whether Claude Desktop can see the same files Serena is indexing;
• restarting Claude Desktop after every config change.

How to Use Serena MCP Server

Once Serena MCP is connected, the next step is to activate and index your project.

Activate the Project

Tell the LLM which project Serena should work on:

Activate the project /path/to/my_project using Serena.

Serena currently works best when one project is active at a time. If the assistant seems to inspect the wrong repository, activate the project again explicitly.

Index the Project

For large projects, indexing improves symbol search and navigation:

uvx --from git+https://github.com/oraios/serena serena project index

Indexing is especially useful when you want the assistant to find functions, classes, references, or module boundaries without reading the whole repository manually.

Use Symbol-Level Editing

Serena MCP is most useful for operations such as:

• finding symbols by name;
• inserting code after a class or function;
• replacing a function body;
• searching references;
• saving project memories for later sessions.

For small one-file edits, plain file tools may be enough. Serena becomes more valuable as the codebase and task complexity grow.

Dashboard and Logs

By default, Serena MCP launches a web dashboard, usually at:

http://localhost:24282/dashboard/index.html

This localhost URL is expected: it is a local dashboard for logs and server control, not a public production URL. Use it to check startup errors, tool calls, and zombie server processes after a client exits.

Serena MCP with Codex and Other Clients

Codex OpenAI CLI

Codex may require a special Serena context. Add a server config like this to ~/.codex/config.toml:

[mcp_servers.serena]
command = "uvx"
args = [
  "--from",
  "git+https://github.com/oraios/serena",
  "serena",
  "start-mcp-server",
  "--context",
  "codex"
]

After startup, explicitly activate your project:

Activate the current dir as project using serena.

Codex may display some MCP tool executions as failed even when the underlying action succeeds, so verify through logs and actual file changes.

Cursor, Cline, Roo-Code, Windsurf, and Other MCP Clients

Serena MCP can integrate with any client that supports the Model Context Protocol. For IDE-style clients, prefer:

--context ide-assistant

Using Serena through non-Claude clients may require API keys and can incur LLM usage costs depending on the client.

Common Serena MCP Problems and Fixes

Serena MCP is installed but no tools appear

Check whether the client actually restarted after the MCP config was saved. Also confirm the command path is absolute and available in the environment where the client runs.

Serena MCP starts but edits the wrong project

Activate the project explicitly and make sure the --project path points to the repository you want to edit.

Claude Desktop registers Serena but never uses it

Try disabling overlapping MCP servers temporarily, especially file-system tools with similar capabilities. Tool-name conflicts or client tool-selection behavior can make Serena appear unused.

Windows config works in terminal but not Claude Desktop

Claude Desktop may not inherit the same PATH as your terminal. Use absolute paths, or call through wsl.exe if Serena is installed inside WSL2.

The dashboard opens at localhost

That is expected. The local dashboard is used for logs and shutdown controls. It is not a leaked deployment URL.

FAQ

What is Serena MCP used for?

Serena MCP is used to give AI coding assistants IDE-like code understanding through MCP. It helps with symbol search, code navigation, project indexing, and more precise edits.

How do I install Serena MCP?

The fastest install path is to run it with uvx:

uvx --from git+https://github.com/oraios/serena serena start-mcp-server

Then add that command to your MCP client config.

How do I configure Serena MCP for Claude Code?

Run this inside your project directory:

claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context ide-assistant --project $(pwd)

Then restart Claude Code or open a fresh session.

Does Serena MCP work on Windows?

Yes, but Windows users often need to decide whether Serena runs in native Windows or WSL2. If it runs in WSL2, configure Claude Desktop to call it through wsl.exe.

Why should I use Serena MCP instead of normal file search?

Normal file search is enough for small edits. Serena MCP is more useful when you need codebase-level understanding, symbol-aware navigation, project memory, and precise edits across a larger repository.