Serena Cursor

You can run Serena as an MCP server to enable powerful, semantically aware coding assistance directly from your LLM, with tooling to explore, edit, and execute code inside your project. This setup lets you connect an MCP client to Serena and perform guided, autonomous coding tasks across your codebase while preserving a clean separation between model work and your local environment.

How to use

Connect an MCP client to Serena to start coding with semantic code retrieval and editing. Start Serena as an MCP server locally or via a container, then configure your client to launch the server and point to the correct project. Use the client to activate a project, read the initial instructions, and request actionable changes. Serena’s tools enable you to read, write, and execute code, inspect logs, and view terminal output, so you can guide or automate tasks end-to-end from analysis to implementation.

How to install

Prerequisites: you need a runtime capable of launching an MCP server (the examples use UV runtimes) and a client that can connect to an MCP server. You do not need an API key for Serena when using the MCP server approach.

1. Local installation and run using UV

2. Using UVX to run directly from the repository

3. Docker (experimental) to isolate the environment and run the MCP server

To start locally with a standard installation:

git clone https://github.com/oraios/serena cd serena cp src/serena/resources/serena_config.template.yml serena_config.yml uv run serena-mcp-server

To run the latest version from the repository without a local installation:

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

To run via 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

## Configuration

Serena’s behavior is configured through a combination of a global config file, per-session command-line options, and per-project settings. You can adjust the context, modes, logging, and tool availability to tailor Serena to your workflow. You can also enable a web dashboard for monitoring logs and controlling the server, and you can enable a GUI tool when supported by your client.

## Project activation and indexing

Activate a project by its absolute path or by name if it was previously activated. Serena will generate a per-project config file and index the project to accelerate tool usage. For large projects, indexing is recommended to speed up the first tool invocation.

## Claude Code and Claude Desktop integration

Add Serena as an MCP server in Claude environments to make Claude Code and Claude Desktop more capable. Provide the server command to run Serena and set the appropriate context and project. After setup, tell Claude to read the initial instructions to receive Serena’s usage guidance.

## Other MCP clients and configurations

Serena can be connected to through multiple MCP clients. When configuring, prefer the ide-assistant context and ensure the server command and arguments align with each client’s startup requirements. You may run Serena via UV, UVX, or Docker depending on your environment.

## Troubleshooting basics

If you encounter issues, verify absolute paths, check that Serena and the language servers are installed correctly, and review the logs. Be aware that some clients may fail to terminate the MCP server process automatically; use Serena’s dashboard to shut it down when needed.

## Notes on onboarding and memories

When a session starts, Serena may onboard by reading project content and creating memories stored under .serena/memories/. These memories help Serena recall relevant context in future interactions.

## Available tools

### activate\_project

Activates a project by name or absolute path, creating a project context for Serena to operate within.

### check\_onboarding\_performed

Returns whether onboarding has already been completed for the active project.

### create\_text\_file

Creates or overwrites a text file within the active project directory.

### delete\_lines

Deletes a range of lines within a file.

### delete\_memory

Removes a memory from Serena's per-project memory store.

### execute\_shell\_command

Executes a shell command from Serena, enabling code generation tasks that involve running external tools.

### find\_referencing\_code\_snippets

Finds code snippets where the symbol at a given location is referenced.

### find\_referencing\_symbols

Finds symbols that reference a given symbol, optionally filtered by type.

### find\_symbol

Performs a global or local search for symbols by name or substring.

### get\_active\_project

Retrieves the currently active project name and lists available projects.

### get\_current\_config

Prints the current Serena configuration, including active modes, tools, and context.

### get\_symbols\_overview

Provides an overview of top-level symbols defined in a file or directory.

### initial\_instructions

Fetches the initial system instructions for the current project when the environment restricts prompt customization.

### insert\_after\_symbol

Inserts content after the end of a symbol's definition.

### insert\_at\_line

Inserts content at a specific line in a file.

### insert\_before\_symbol

Inserts content before the beginning of a symbol's definition.

### list\_dir

Lists files and directories in a given directory, with optional recursive listing.

### list\_memories

Lists memories stored for the active project.

### onboarding

Performs onboarding to understand project structure and essential tasks for testing or building.

### prepare\_for\_new\_conversation

Provides instructions to prepare for a new conversation, ensuring necessary context is available.

### read\_file

Reads a file within the project directory.

### read\_memory

Reads a memory by name from Serena's project memory store.

### replace\_lines

Replaces a range of lines within a file with new content.

### replace\_symbol\_body

Replaces the full definition body of a symbol.

### restart\_language\_server

Restarts the language server to apply changes or recover from editing issues.

### search\_for\_pattern

Searches for a pattern within the project.

### summarize\_changes

Provides instructions for summarizing changes made to the codebase.

### switch\_modes

Activates one or more modes by name to tailor Serena's behavior.

### think\_about\_collected\_information

Thinking tool for evaluating the sufficiency of collected information.

### think\_about\_task\_adherence

Thinking tool for assessing whether the task is still on track.

### think\_about\_whether\_you\_are\_done

Thinking tool to determine if the task is truly completed.

### write\_memory

Writes a named memory to Serena's project memory store for future interactions.