Serena MCP server

Serena is a powerful MCP (Model Context Protocol) server that transforms any LLM into a coding agent with semantic code understanding. It provides symbolic code retrieval and editing capabilities, working directly within your codebase like an IDE would.

Installation Options

Using uvx (Recommended)

Run Serena directly from the repository without local installation:

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

Local Installation

1. Clone the repository and navigate to it:

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

2. Optionally edit the configuration file:

   uv run serena config edit
   

3. Run the server:

   uv run serena start-mcp-server
   

Using Docker (Experimental)

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

Using Nix

nix run github:oraios/serena -- start-mcp-server --transport stdio

Configuration

Serena can be configured in several ways:

1. Global configuration file at ~/.serena/serena_config.yml
2. Command-line arguments passed to start-mcp-server
3. Project-specific configuration in .serena/project.yml
4. Through contexts and modes

Generate a project configuration with:

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

Project Activation

Activate a project by providing a path or name:

# In your client, ask the LLM:
# "Activate the project /path/to/my_project"
# or
# "Activate the project my_project"

For larger projects, index them first to improve performance:

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

Client Integration

Claude Code

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

Codex

Add to ~/.codex/config.toml:

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

Then in Codex, ask to "Activate the current dir as project using serena"

Claude Desktop

Edit claude_desktop_config.json and add:

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

Detailed Usage

Modes and Contexts

Serena uses contexts and modes to customize behavior:

• Contexts (set at startup, cannot be changed):

  • desktop-app: For desktop applications (default)
  • agent: For autonomous agent scenarios
  • ide-assistant: For IDE integrations

• Modes (can be changed during a session):

  • planning: For planning and analysis
  • editing: For code modification
  • interactive: For conversational interaction
  • one-shot: For tasks completed in a single response

Set context at startup:

serena start-mcp-server --context ide-assistant

Set modes at startup:

serena start-mcp-server --mode planning --mode no-onboarding

Onboarding and Memories

Serena stores project-specific memories in .serena/memories/ that help it understand your project across sessions. These can be manually edited or extended.

Preparing Your Project

For best results:

• Structure your codebase with clear modules and functions
• Start from a clean git state
• Ensure good test coverage and meaningful logging
• On Windows, set git config core.autocrlf true

Troubleshooting

• Check Serena's dashboard at http://localhost:24282/dashboard/index.html
• Look for orphaned processes if clients fail to terminate the MCP server
• Always use absolute paths in configuration

Available Tools

Serena provides numerous tools including:

• activate_project: Activates a project
• find_symbol: Searches for code symbols
• find_referencing_symbols: Finds symbol references
• insert_after_symbol, insert_before_symbol: Modify code at the symbol level
• execute_shell_command: Runs shell commands
• read_file, create_text_file: File operations
• read_memory, write_memory: Memory management
• And many more specialized tools for code understanding and manipulation

The full set of tools enables sophisticated code navigation, analysis, and editing capabilities that make any LLM more effective at working with your codebase.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "serena" '{"command":"uvx","args":["--from","git+https://github.com/oraios/serena","serena-mcp-server"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect