Serena MCP: Detailed User Guide (Installation, Configuration, and Practical Usage)

Serena MCP is a powerful open-source AI coding agent toolkit that runs as an MCP server. It leverages the Language Server Protocol (LSP) to provide symbol-level understanding, addressing the shortcomings of traditional AI programming tools based on plain text search (e.g., RAG) when dealing with complex codebases.

What makes Serena MCP unique is that it can be used for free via the Claude Desktop application, even on the free tier, thus avoiding API costs.

This guide will walk you through installing, configuring, and using Serena MCP across different clients, including Claude Code Serena integration.

---

1. Environment Setup and Server Launch

Serena MCP depends on a Python environment, and the use of the uv tool is recommended.

1.1 Prerequisite: Install uv

All command-line operations of Serena MCP are powered by uv, so you need to install it first.

1.2 Start the Serena MCP Server

Serena MCP must run as an MCP server. Typically, the client (e.g., Claude Desktop) launches it as a subprocess and communicates via standard input/output (stdio).

Quick Start with uvx (Recommended)

You can run the latest version of Serena MCP directly from the repository using uvx, without cloning locally:

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

Local Installation and Run

1. Clone the repo:

   git clone https://github.com/oraios/serena && cd serena

2. Start the server:

   uv run serena start-mcp-server

3. If running outside the install directory, specify it explicitly:

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

Using Docker (Experimental)

Docker provides better isolation and a consistent environment without installing a language server locally. 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

Dashboard and Logs

By default, Serena MCP launches a web dashboard (usually at http://localhost:24282/dashboard/index.html) to display logs and allow users to shut down the MCP server (to prevent zombie processes after clients close).

---

2. Client Configuration (Integration Across Systems)

Serena MCP can integrate with any client that supports the Model Context Protocol (MCP).

2.1 Claude Desktop (Windows/macOS)

This is the best way to use Serena MCP for free, since it works even on Claude’s free tier.

1. Open Claude Desktop → File / Settings / Developer / MCP Servers / Edit Config.

2. This opens claude_desktop_config.json. Add Serena MCP under mcpServers:

   Example config using uvx:

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

3. After saving, fully quit Claude Desktop and restart.

4. Troubleshooting: If Claude registers Serena MCP but doesn’t call its tools, disable FileSystemMCP (tool name conflicts are possible).

Windows WSL2 Integration

If running Claude Desktop on Windows but Serena MCP inside WSL2 (Ubuntu), prefix the command with wsl.exe -d Ubuntu in claude_desktop_config.json.

2.2 Codex (OpenAI CLI)

Codex does not fully support MCP, so a special context is required.

1. Add this to ~/.codex/config.toml (create the file if missing):

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

   Note: You must use the --context codex flag with Serena MCP.

2. Activate project after startup: Since Codex uses global config, you must explicitly activate your project:

   "Activate the current dir as project using serena"

3. Logs and troubleshooting: Codex often shows tool execution as failed even when successful (likely a bug).

2.3 Claude Code Serena (CLI Integration)

In your project directory, you can add Claude Code Serena support with:

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

This ensures Serena MCP is available directly in Claude Code Serena workflows, making symbol-level editing and project management seamless.

2.4 Other MCP Clients (Cursor, Cline, Roo-Code, Windsurf)

Since Serena MCP runs as an MCP server, it can be integrated with any MCP-compatible client, including IDE extensions and VSCode-like IDEs.

• Recommendation: Always use -context ide-assistant in args.
• Note on cost: Using Serena MCP via these clients still incurs LLM API fees.

2.5 Local GUIs and Other LLMs (Agno, OpenWebUI)

Serena MCP is not limited to Claude. It can be used with Agno, OpenWebUI, or Jan, and integrated with Gemini or locally hosted models (Ollama, LM Studio).

• With non-Claude clients, you usually need an API key, which means added cost.

---

3. Practical Usage and Workflow

Serena MCP is designed to provide IDE-grade tools like symbol search (find_symbol) and symbol-level insertion (insert_after_symbol), rather than relying on file reads or plain text search.

3.1 Project Activation and Indexing

Before using Serena MCP tools, you must tell the LLM which project it is working on.

• Activate project:

  "Activate the project /path/to/my_project"

• Single project restriction: Serena MCP currently supports one project at a time.

• Indexing: For large projects, indexing speeds up tool performance:

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

3.2 First-Time Use: Onboarding and Memory

Serena MCP has a unique memory system.

• Onboarding: On first run, Serena MCP analyzes project structure, key details, and business logic, then stores results as memory files under .serena/memories/.
• Memory usage: In later sessions, the LLM selectively reads these files for better context.
• Bypassing onboarding: You can skip it by creating a dummy file in .serena/memories/.

3.3 Coding, Editing, and Autonomous Agent Behavior

Serena MCP supports advanced workflows:

• Symbol-level editing: Use replace_symbol_body for accurate edits.
• Autonomous correction (Agent Loop): With execute_shell_command enabled (default in Claude Desktop and Claude Code Serena setups), Serena MCP can run code/tests and auto-correct errors.
• Security note: Since this executes arbitrary commands, review parameters carefully. For analysis-only mode, set read_only: true in project config.

3.4 Avoiding Context Overload

For long/complex tasks or near context limits, start a new conversation.

• Use prepare_for_new_conversation to save a summary of the current state as memory. In a new session, reload that memory to continue seamlessly.

3.5 Contexts and Modes

You can adjust Serena MCP behavior with Contexts and Modes:

• Contexts: Defined at startup (e.g., desktop-app default, agent for more autonomy, or ide-assistant for IDE integration such as Claude Code Serena).
• Modes: Switch dynamically for task focus (e.g., planning, editing, one-shot). Use switch_modes to toggle modes.