Serena MCP server for AI agents

The Serena MCP Server provides powerful tools for code analysis and editing through a protocol that integrates with various AI assistants. This article covers how to install and use this server to enhance your coding workflow.

Serena turns large language models into effective coding agents by providing semantic code retrieval and editing capabilities. When connected to tools like Claude Desktop, Claude Code, or other MCP-compatible clients, it enables AI assistants to understand and manipulate code at a symbolic level.

Installation Options

Local Installation

Clone the repository and navigate to it:

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

Optionally create a configuration file:

mkdir ~/.serena
cp src/serena/resources/serena_config.template.yml ~/.serena/serena_config.yml

Run the server using uv:
```
uv run serena-mcp-server
```

Using uvx

For a quick installation-free approach:

On Windows:

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

On other operating systems:

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

Using Docker (Experimental)

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

Configuring with Claude Desktop

Open Claude Desktop and navigate to File → Settings → Developer → MCP Servers → Edit Config
Add the Serena configuration:

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

Save and restart Claude Desktop

Configuring with Claude Code

From your project directory, run:

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

Then in Claude Code, ask to "read Serena's initial instructions" or run /mcp__serena__initial_instructions to load the instruction text.

Using SSE Mode

If you prefer HTTP-based communication:

uv run serena-mcp-server --transport sse --port 9121

Configure your client to connect to http://localhost:9121/sse.

Project Activation

To start working with a project:

Ask the AI to activate your project by providing a path:
- "Activate the project /path/to/my_project"
- "Activate the project my_project" (if previously activated)
For larger projects, index your project to improve performance:
```
uv run --directory /abs/path/to/serena index-project
```

Key Features

Semantic Code Analysis: Serena uses language servers to understand code at a symbolic level
Project-Specific Memory: Stores information about your project for future sessions
Multiple Programming Languages: Supports Python, TypeScript/JavaScript, PHP, Go, Rust, C#, Java and more
Shell Command Execution: Can run tests, build processes, and other commands
Web Dashboard: Monitor logs and tool usage at http://localhost:24282/dashboard/index.html

Customization

Serena's behavior can be customized through:

The global ~/.serena/serena_config.yml file
Command-line arguments passed to the server
Project-specific .serena/project.yml files
Active modes (planning, editing, interactive, etc.)

Usage Tips

Start from a clean git state for better tracking of changes
Projects with good test coverage and well-structured code work best
Use the planning mode before implementation for complex tasks
Create memories to continue work across multiple sessions
Use the dashboard to monitor logs and shut down the server if needed

Serena works best with well-structured code and can significantly enhance your coding workflow by enabling AI assistants to understand and modify your codebase with greater precision.

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