Running Serena

Running Serena#

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

  • varies ways of running Serena

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

  • other useful commands.

Ways of Running Serena#

In the following, we will refer to the command used to run Serena as <serena>, which you should replace with the appropriate command based on your chosen method.

Using uvx#

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 --from git+https://github.com/oraios/serena serena

Explore the CLI to see some of the customization options that serena provides (more info on them below).

Local Installation#

  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 (Experimental)#

Warning

Docker support is currently experimental with several limitations.

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

Replace /path/to/your/projects with the absolute path to your projects directory. The Docker approach provides:

  • Better security isolation for shell command execution

  • No need to install language servers and dependencies locally

  • Consistent environment across different systems

Alternatively, use docker compose with the compose.yml file provided in the repository.

See our Docker Setup documentation for more detailed setup instructions, configuration options, and known limitations.

Using Nix#

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.

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.

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

For example, to run the server in stdio mode via uvx, you would run:

uvx --from git+https://github.com/oraios/serena 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 instead the 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.

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

For example, to run the Serena MCP server in streamable HTTP mode on port 9121 using uvx, you would run

uvx --from git+https://github.com/oraios/serena serena start-mcp-server --transport streamable-http --port 9121

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

Note that while 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.

  • --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)

  • --enable-web-dashboard <true|false>: enable or disable the web dashboard (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 generate-yml

# indexing the project in the current directory
<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!

Contents