Serena MCP server for AI agents

The Serena MCP server enables LLMs to interact with your codebase using semantic code understanding and editing capabilities. It works by providing IDE-like tools that allow models to find, analyze, and modify code at the symbol level rather than just operating on raw text.

Installation

Using uvx (Recommended)

The quickest way to get started with Serena is using uvx, which allows you to run Serena directly from the repository:

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

Local Installation

Alternatively, you can install Serena locally:

Clone the repository:

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

Run the server with uv:
```
uv run serena start-mcp-server
```

Using Docker

For better security isolation, you can run Serena via Docker:

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

If you use Nix with flakes enabled:

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

Configuration

Serena can be configured in several ways:

Through the global config file at ~/.serena/serena_config.yml:

uvx --from git+https://github.com/oraios/serena serena config edit

Through command-line arguments when starting the MCP server
Through project-specific configuration in .serena/project.yml

Usage with Different Clients

Claude Code

From your project directory:

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

Claude Desktop

Edit Claude Desktop's configuration file (File → Settings → Developer → MCP Servers → Edit Config):

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

Codex

Add to your ~/.codex/config.toml:

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

Then activate a project by telling Codex: "Activate the current dir as project using serena"

Project Activation and Indexing

When working with Serena, you need to activate a project first. There are two ways to do this:

Configure Serena to automatically activate a project at startup:
```
serena start-mcp-server --project /path/to/project
```
Ask the LLM to activate a project: "Activate the project /path/to/my_project" or "Activate the project my_project"

For larger projects, it's recommended to pre-index your project to speed up Serena's tools:

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

Advanced Features

Modes and Contexts

Serena supports different contexts and modes to customize its behavior:

Contexts (set at startup):
- desktop-app: For applications like Claude Desktop (default)
- agent: For more autonomous behavior
- ide-assistant: For IDE integration
Modes (can be changed during a session):
- planning: For analysis and planning tasks
- editing: For code modification tasks
- interactive: For conversational interaction
- one-shot: For single-response tasks

Set a 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 knowledge as "memories" in .serena/memories/ to improve future interactions. After first activating a project, Serena will perform an onboarding process to learn about your codebase.

You can:

List memories: Ask Serena to "list memories"
Read a memory: Ask Serena to "read the memory about [topic]"
Create a memory: Ask Serena to write a memory about an important aspect of your project

Serena's Logs and Dashboard

Serena provides a web dashboard for monitoring and control:

By default, accessible at http://localhost:24282/dashboard/index.html
Shows logs and tool usage statistics
Allows shutting down the Serena server (useful when clients fail to clean up processes)

Best Practices

Structure your codebase well - Serena works best with well-organized code
Start from a clean git state - Makes it easier to track changes
Use proper line endings - On Windows, set git config core.autocrlf true
Have good tests and logging - Helps Serena validate its changes
Plan before implementing - Use planning mode for complex tasks
Manage context efficiently - For long tasks, create a memory summary and continue in a new conversation

Serena is a powerful tool that enhances LLMs with IDE-like capabilities, making them much more effective at understanding and modifying complex codebases.

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