Running Serena

Running Serena#

Serena is a command-line tool with a variety of sub-commands. This section describes

  • how to run Serena in general

  • how to run and configure the most important command, i.e. starting the MCP server

  • other useful commands.

The main way to run Serena is to use the installed version, which should be available in your system PATH as serena.

In general, to get help, append --help to the command, i.e.

serena --help
serena <command> --help

Running the MCP Server#

Given your preferred method of running Serena, you can start the MCP server using the start-mcp-server command:

serena start-mcp-server [options]

Note that no matter how you run the MCP server, Serena will, by default, start a web-based dashboard on localhost that will allow you to inspect the server’s operations, logs, and configuration.

Tip

By default, Serena will use language servers for code understanding and analysis.
With the Serena JetBrains Plugin, we recently introduced a powerful alternative, which has several advantages over the language server-based approach.

Standard I/O Mode#

The typical usage involves the client (e.g. Claude Code, Codex or Cursor) running the MCP server as a subprocess and using the process’ stdin/stdout streams to communicate with it. In order to launch the server, the client thus needs to be provided with the command to run the MCP server.

Note

MCP servers which use stdio as a protocol are somewhat unusual as far as client/server architectures go, as the server necessarily has to be started by the client in order for communication to take place via the server’s standard input/output streams. In other words, you do not need to start the server yourself. The client application (e.g. Claude Desktop) takes care of this and therefore needs to be configured with a launch command.

Communication over stdio is the default for the Serena MCP server, so in the simplest case, you can simply run the start-mcp-server command without any additional options.

serena start-mcp-server

See the section “Configuring Your MCP Client” for specific information on how to configure your MCP client (e.g. Claude Code, Codex, Cursor, etc.) to use such a launch command.

Streamable HTTP Mode#

When using Streamable HTTP mode, you control the server lifecycle yourself, i.e. you start the server and provide the client with the URL to connect to it.

Simply provide start-mcp-server with the --transport streamable-http option and optionally provide the desired port via the --port option. For example, to start the server on port 9121, run

serena start-mcp-server --transport streamable-http --port <port>

and then configure your client to connect to http://localhost:9121/mcp.

By default, only connections from localhost are allowed; pass the --host <listen_address> option to configure the listen address and allow remote connections if needed (but be aware of the security implications of doing so).

When to use. Note that Serena is a stateful MCP server, and only one coding project can be active at a time. Therefore, starting a single Serena instance and connecting it to multiple clients is only appropriate if all clients will be working on the same project.
If you want several agents to work on different projects, making each client/agent start its own server in stdio mode is likely the best option. See section The Project Workflow for more information on how to manage projects in Serena.

The legacy SSE transport is also supported (via --transport sse with corresponding /sse endpoint), its use is discouraged.

MCP Server Command-Line Arguments#

The Serena MCP server supports a wide range of additional command-line options. Use the command

<serena> start-mcp-server --help

to get a list of all available options.

Some useful options include:

  • --project <path|name>: specify the project to work on by name or path.

  • --project-from-cwd: auto-detect the project from current working directory
    (looking for a directory containing .serena/project.yml or .git in parent directories and activating the containing directory as the project root, if any). This option is intended for CLI-based agents like Claude Code, Gemini and Codex, which are typically started from within the project directory and which do not change directories during their operation.

  • --language-backend JetBrains: use the Serena JetBrains Plugin as the language backend (overriding the default backend configured in the central configuration)

  • --context <context>: specify the operation context in which Serena shall operate

  • --mode <mode>: specify one or more modes to enable (can be passed several times)

  • --open-web-dashboard <true|false>: whether to open the web dashboard on startup (enabled by default)

Other Commands#

Serena provides several other commands in addition to start-mcp-server, most of which are related to project setup and configuration.

To get a list of available commands, run:

<serena> --help

To get help on a specific command, run:

<serena> <command> --help

In general, add --help to any command or sub-command to get information about its usage and available options.

Here are some examples of commands you might find useful:

# get help about a sub-command
serena> tools list --help

# list all available tools
serena> tools list --all

# get detailed description of a specific tool
serena> tools description find_symbol

# creating a new Serena project in the current directory 
serena project create

# creating and immediately indexing a project
serena project create --index

# indexing the project in the current directory (auto-creates if needed)
serena project index

# run a health check on the project in the current directory
serena project health-check

# check if a path is ignored by the project
serena project is_ignored_path path/to/check

# edit Serena's configuration file
serena config edit

# list available contexts
serena context list

# create a new context
serena context create my-custom-context

# edit a custom context
serena context edit my-custom-context

# list available modes
serena mode list

# create a new mode
serena mode create my-custom-mode

# edit a custom mode
serena mode edit my-custom-mode

# list available prompt definitions
serena prompts list

# create an override for internal prompts
serena prompts create-override prompt-name

# edit a prompt override
serena prompts edit-override prompt-name

Explore the full set of commands and options using the CLI itself!

Alternative Ways of Running Serena#

Depending on your requirements, you may want to run Serena in different ways. When applying one of these approaches, replace serena in commands mentioned throughout the documentation with the respective command and options. The same applies to serena-hooks commands.

Using uvx to Run the Latest Source Version#

uvx is part of uv. It can be used to run the latest version of Serena directly from the repository, without an explicit local installation.

uvx -p 3.13 --from git+https://github.com/oraios/serena serena

This was previously the main way of running Serena. Since this has the downside that every new commit in the repository will trigger a (potentially slow) re-synchronization, an installation of Serena should usually be preferred. If you should experience timeouts when connecting the MCP server, consider switching.
If, however, the synchronisation is fast enough for you, this is still a good option.

Running from Cloned Source#

  1. Clone the repository and change into it.

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

  2. Run Serena via

    uv run serena

    when within the serena installation directory.
    From other directories, run it with the --directory option, i.e.

     uv run --directory /abs/path/to/serena serena

Note

Adding the --directory option results in the working directory being set to the Serena directory. As a consequence, you will need to specify paths when using CLI commands that would otherwise operate on the current directory.

Using Docker#

The Docker approach offers several advantages:

  • better security isolation for shell command execution

  • no need to install language servers and dependencies locally

  • consistent environment across different systems

You can run the Serena MCP server directly via Docker as follows, assuming that the projects you want to work on are all located in /path/to/your/projects:

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

This command mounts your projects into the container under /workspaces/projects, so when working with projects, you need to refer to them using the respective path (e.g. /workspaces/projects/my-project).

Alternatively, you may use Docker compose with the compose.yml file provided in the repository. See our advanced Docker usage documentation for more detailed instructions, configuration options, and limitations.

Note

Docker usage is subject to limitations; see the advanced Docker usage documentation for details.

Using Nix to Run the Latest Source Version#

If you are using Nix and have enabled the nix-command and flakes features, you can run Serena using the following command:

nix run github:oraios/serena -- <command> [options]

You can also install Serena by referencing this repo (github:oraios/serena) and using it in your Nix flake. The package is exported as serena.

Contents