Installing UV Package Manager

UV serves as Serena's primary dependency manager, replacing traditional pip-based workflows with significantly faster installation and more reliable dependency resolution. The UV project represents a modern approach to Python tooling, built in Rust for exceptional performance.

curl -LsSf https://astral.sh/uv/install.sh | sh

After installation, reload your shell configuration to ensure UV is available in your PATH:

source ~/.bashrc

Verify successful installation by checking the UV version:

uv --version

Method 1: Direct Execution with UVX (Recommended for Quick Start)

The UVX approach provides the fastest path to running Serena without local installation overhead. This method automatically fetches the latest version from the GitHub repository and executes it in an isolated environment, making it ideal for evaluation and testing scenarios.

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

This command initiates the MCP server using stdio transport, the standard protocol for MCP client-server communication. Most MCP clients like Claude Desktop expect this configuration by default.

Method 2: Local Installation from Repository (Recommended for Development)

Local installation provides complete control over Serena's configuration and enables custom modifications to the codebase. This approach is essential for organizations requiring code audits, custom tool development, or offline operation capabilities.

Step 1: Clone the Serena repository to your local system

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

Step 2: (Optional) Edit the global configuration file

uv run serena config edit

This opens ~/.serena/serena_config.yml in your default editor. Configuration changes apply globally across all projects and clients unless overridden by project-specific settings.

Step 3: Launch the MCP server

uv run serena start-mcp-server

When executing from outside the installation directory, specify the absolute path:

uv run --directory /absolute/path/to/serena serena start-mcp-server

Method 3: Docker Containerized Deployment (Recommended for Security)

Docker deployment provides enhanced security isolation for shell command execution while eliminating local dependency management. This approach is particularly valuable in enterprise environments with strict security policies or when working with untrusted codebases.

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

Replace /path/to/projects with your actual projects directory. The volume mount enables Serena to access your codebase while maintaining container isolation for security purposes.

Method 4: Nix Package Manager (For NixOS Users)

Nix users benefit from declarative, reproducible installations that integrate seamlessly with existing Nix configurations. This approach is ideal for organizations using Nix for system configuration management.

nix run github:oraios/serena -- start-mcp-server --transport stdio

Claude Code Integration: Premium Performance Enhancement

Claude Code represents Anthropic's official CLI coding agent, and Serena integration transforms it into an exceptionally powerful development tool. The combination delivers superior token efficiency and more precise code modifications compared to Claude Code's standalone capabilities.

Navigate to your project root directory and execute:

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

The --context ide-assistant parameter optimizes Serena's toolset and prompting strategy for IDE-integrated workflows. This context disables redundant tools that Claude Code already provides while enhancing symbolic code navigation capabilities.

OpenAI Codex CLI Configuration

OpenAI's Codex CLI provides another terminal-based coding agent option. Serena integration requires the specialized codex context due to Codex's non-standard MCP implementation that requires tool description massaging for compatibility.

Edit ~/.codex/config.toml (create if absent) and add:

[mcp_servers.serena]
command = "uvx"
args = ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--context", "codex"]

Unlike Claude Code's per-project MCP configuration, Codex registers MCP servers globally. After Codex initializes, activate your project explicitly:

Claude Desktop Application Setup

Claude Desktop provides a user-friendly GUI experience for Claude interactions with full MCP server support. While official builds exist for Windows and macOS, Ubuntu users can leverage the community-maintained Debian implementation for equivalent functionality.

Access the configuration editor through File → Settings → Developer → MCP Servers → Edit Config. This opens claude_desktop_config.json for direct editing.

UVX Remote Execution Configuration:

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

Web Dashboard Configuration

The web dashboard launches automatically by default, providing real-time visibility into Serena's operations. Access the dashboard at http://localhost:24282/dashboard/index.html (port may increment if 24282 is occupied).

Dashboard features include:

• Real-time Log Streaming: Complete visibility into tool invocations, language server communications, and error conditions
• Usage Statistics: Tool execution metrics and performance analytics (enable with record_tool_usage_stats: true in config)

Language Server Initialization Failures

Symptom: Tools fail with "language server not initialized" errors.

Solution: Verify the language-specific dependency (e.g., gopls) is in your PATH. You may need to restart the language server using the restart_language_server tool.

Tool Permission Denied

Symptom: Shell or file operations fail.

Solution: Ensure the user running the MCP server has write permissions to the project directory. Avoid running Serena as root; use a standard user account with appropriate group memberships.