Serena MCP server

Serena is a powerful MCP (Model Context Protocol) server that transforms large language models like Claude into full-featured coding agents with deep code understanding capabilities. It provides semantic code retrieval and editing tools that allow LLMs to work directly on your codebase, similar to what IDE capabilities would offer.

Installation

Setting up Serena requires the uv package manager:

# Install uv first if you don't have it
# Follow instructions at https://docs.astral.sh/uv/getting-started/installation/

# Clone the repository (optional)
git clone https://github.com/oraios/serena
cd serena

# Create a config file (optional)
cp src/serena/resources/serena_config.template.yml serena_config.yml

Alternatively, you can use Serena directly without cloning by using uvx:

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

Configuring with Claude Desktop

To use Serena with Claude Desktop (available for Windows and macOS):

1. Go to File → Settings → Developer → MCP Servers → Edit Config
2. Add the following to the JSON configuration (adjust paths accordingly):

{
    "mcpServers": {
        "serena": {
            "command": "/abs/path/to/uv",
            "args": ["run", "--directory", "/abs/path/to/serena", "serena-mcp-server"]
        }
    }
}

For Windows paths with backslashes, be sure to escape them properly (e.g., C:\\Users\\name).

Working with Projects

Project Activation

Ask the LLM to activate a project by providing an absolute path:

Please activate the project at /path/to/my/project

For previously activated projects, you can refer to them by name:

Please activate the my-project project

The first time you activate a project, Serena will perform an onboarding process to analyze your codebase and create project memories.

Project Configuration

Serena creates a .serena directory in your project with configuration files:

• .serena/project.yml - Project-specific settings
• .serena/memories/ - Directory containing project memories

Using Modes and Contexts

Serena provides different modes and contexts to adapt its behavior to different scenarios:

Contexts

Contexts define the environment in which Serena operates and are set at startup:

serena-mcp-server --context ide-assistant

Available contexts:

• desktop-app (default): Optimized for desktop applications like Claude Desktop
• ide-assistant: For integration with IDEs like VSCode or Cursor
• agent: For more autonomous agent scenarios

Modes

Modes refine Serena's behavior for specific tasks and can be changed during a session:

Please switch to planning and one-shot modes

Available modes:

• planning: For analysis and planning tasks
• editing: For direct code modification
• interactive: For conversational back-and-forth
• one-shot: For tasks to be completed in a single response
• no-onboarding: Skips the initial onboarding process

Key Tools and Capabilities

Serena provides various tools for code navigation, analysis, and editing:

Code Analysis

• Finding symbols and references across the codebase
• Getting an overview of file/directory structure
• Searching for patterns in code

Code Editing

• Creating and modifying files
• Inserting, replacing, and deleting lines of code
• Editing at the symbol level (functions, classes, methods)

Shell Operations

• Executing shell commands
• Running tests and build commands

Memory Management

• Creating and reading project memories
• Preparing summaries for continuing work in new sessions

Practical Usage Tips

1. Start from a clean state: Begin with a clean git state for easier tracking of changes.

2. For Windows users: Set git config core.autocrlf true to avoid line ending issues.

3. Plan before implementing: For complex tasks, start with a planning session before implementation.

4. Use project memories: After completing onboarding, continue in a new conversation and leverage the created memories.

5. Handling context limits: For long tasks, use the prepare_for_new_conversation tool to create a summary and continue in a fresh session.

6. Structured code works best: Serena performs best with well-structured, modular codebases with good type annotations.

7. Enable the dashboard: The web dashboard (http://localhost:24282/dashboard/index.html by default) shows logs and allows shutting down the server.

Troubleshooting

• If you experience issues with the standard stdio protocol, try using SSE mode:

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

• Check for hanging processes if Serena seems to crash or disappear.

• Use the web dashboard to monitor logs and properly shut down the server.

• Restart the language server if edits made outside of Serena aren't being detected.

How to add this MCP server to 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 > MCP and click "Add new global MCP server".

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

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

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 explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.