Serena MCP Installation Guide

Overview

This document covers all known issues and solutions encountered during Serena MCP installation. Based on 5 hours of troubleshooting and references from Chris Han's blog post.

Key Requirements

web_dashboard: false - Installation fails without this setting.
uv sync - Dependency installation is mandatory.
Global ~/.claude.json - Must use global settings, not project-specific.

Common Installation Failures

Case 1: Official Documentation Method

uvx --from serena-agent serena-mcp-server

Result: Command `serena-mcp-server` not found

Case 2: PyPI Package Installation

uv tool install serena-agent

Result: Installs but no executable found

Case 3: Wrong Command

uvx --from serena-agent serena start-mcp-server

Result: Connection failure in Claude

Case 4: Direct GitHub Installation

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

Result: Still connection failure

Case 5: Missing Web Dashboard Setting

Result: MCP communication failure - stdout/stderr pollution blocks JSON-RPC

Root Cause Analysis

Cause 1: PyPI Package Version Issues

PyPI's `serena-agent` is outdated
Latest version only exists in GitHub repository
GitHub version documentation also partially incorrect

Cause 2: Web Dashboard Interference (Top Priority)

`web_dashboard: True` is set as default
Web dashboard outputs logs to stdout/stderr, interfering with MCP
Claude requires pure JSON-RPC communication but logs are mixed
Required: Set `web_dashboard: false`

Cause 3: Missing Dependency Installation

Failure when `uv sync` not executed after `git clone`
55 essential packages must be installed
Command exists but won't execute without this step

Correct Installation Steps

Prerequisites

macOS/Linux

# Check Python 3.8+
python3 --version

# Check Git
git --version

# Install uv (Python package manager)
# Using Homebrew (macOS)
brew install uv

# Or official install script (Linux/macOS)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Verify installation
uv --version

Windows (WSL2 recommended)

# In WSL2 use Linux commands
# Or in Windows PowerShell
winget install astral-sh.uv

Step 1: Remove Existing Installation

# Check and kill running processes
ps aux | grep serena
# kill [PID]

# Remove uv tools
uv tool uninstall serena-agent 2>/dev/null || echo "Not installed"

# Delete config files
rm -rf ~/.serena
rm -rf .serena

# Delete executables
rm -f ~/.local/bin/serena*

# Clear cache
find ~/.local/share/uv -name "*serena*" -exec rm -rf {} + 2>/dev/null

# Remove existing clone
rm -rf ~/work/serena

Step 2: Local Installation

# Create working directory
mkdir -p ~/work
cd ~/work

# Clone latest version from GitHub
git clone https://github.com/oraios/serena
cd serena

# Important: Install dependencies (required)
uv sync

# Verify success (55 packages installed)
# Installed 55 packages in XXXms

Step 3: Configure Settings

# Create config directory
mkdir -p ~/.serena

# Copy template
cp src/serena/resources/serena_config.template.yml ~/.serena/serena_config.yml

# Required: Disable web dashboard
sed -i 's/web_dashboard: True/web_dashboard: false/g' ~/.serena/serena_config.yml
sed -i 's/web_dashboard_open_on_launch: True/web_dashboard_open_on_launch: false/g' ~/.serena/serena_config.yml

# Or manually edit:
# web_dashboard: false
# web_dashboard_open_on_launch: false

Step 4: Claude Configuration

Create a Python script to automate configuration:

# setup_serena.py
import json
import os
import sys

claude_config = os.path.expanduser('~/.claude.json')

if not os.path.exists(claude_config):
    print("Error: ~/.claude.json not found. Run Claude Code first.")
    sys.exit(1)

with open(claude_config, 'r') as f:
    data = json.load(f)

# Add to global settings
if 'mcpServers' not in data:
    data['mcpServers'] = {}

data['mcpServers']['serena'] = {
    'type': 'stdio',
    'command': 'uv',
    'args': [
        'run',
        '--directory',
        os.path.expanduser('~/work/serena'),
        'serena-mcp-server',
        '--context',
        'ide-assistant'
    ],
    'env': {}
}

# Remove project-specific duplicates
removed_count = 0
for project_path, project_config in data.get('projects', {}).items():
    if 'mcpServers' in project_config and 'serena' in project_config['mcpServers']:
        del project_config['mcpServers']['serena']
        removed_count += 1
        print(f"Removed duplicate Serena config from {project_path}")

with open(claude_config, 'w') as f:
    json.dump(data, f, indent=2)

print(f"\nClaude configuration complete.")
print(f"Serena path: {os.path.expanduser('~/work/serena')}")
if removed_count > 0:
    print(f"Removed {removed_count} duplicate configurations")
print("\nRestart Claude Code now:")
print("1. Exit with Ctrl+C or /exit")
print("2. Restart with: claude --resume")
print("3. Verify with: /mcp")

Run the script:

python3 setup_serena.py

Step 5: Verify and Restart Claude

# Check configuration
grep -A 10 '"serena"' ~/.claude.json

# Test JSON-RPC
cd ~/work/serena
echo '{"jsonrpc":"2.0","method":"initialize","params":{"capabilities":{}},"id":1}' | \
  uv run serena-mcp-server --context ide-assistant 2>/dev/null | head -5

# Restart Claude
# Exit with Ctrl+C or /exit
claude --resume

# Check MCP status
/mcp
# Should show: serena: Connected

Essential Guidelines

DO NOT:

Use `uvx --from serena-agent`
Use `serena start-mcp-server` (starts web dashboard)
Use PyPI package (outdated)
Use project-specific .claude.json settings
Set `web_dashboard: True`
Skip `uv sync`

MUST DO:

Clone directly from GitHub
Install dependencies with `uv sync`
Set `web_dashboard: false`
Use `uv run --directory`
Configure global ~/.claude.json
Remove duplicate configurations

Troubleshooting

For "Failed to connect" errors:

Check web_dashboard setting (top priority)

grep web_dashboard ~/.serena/serena_config.yml

Verify dependency installation
```
cd ~/work/serena && uv sync
```
Check running Serena processes
```
ps aux | grep serena
```
Check ~/.claude.json for duplicates
Verify local clone path
Confirm Claude restart

References

Conclusion

Serena MCP is a powerful tool, but web dashboard settings and dependency installation are crucial for successful installation.

Essential checks:

`web_dashboard: false`
`uv sync` executed
Global settings used

Following this guide precisely will lead to successful installation.