Serena MCP Server: Setup & Configuration Guide (2026)

Serena MCP Server: Setup and Configuration Guide (2026)

Serena is an open-source MCP (Model Context Protocol) server that gives AI assistants deep, code-aware access to your projects. Unlike simple file-reading tools, Serena uses Language Server Protocol (LSP) integration to provide semantic understanding of your codebase -- symbol lookups, go-to-definition, find references, and intelligent code navigation.

This guide covers installing Serena, configuring it for your projects, and connecting it to MCP-compatible clients like Claude Desktop, Cursor, and Claude Code.

What Is Serena?

Serena is built on the MCP standard created by Anthropic. It acts as a bridge between AI models and your codebase, providing:

• Semantic code analysis via LSP (not just text search)
• Symbol resolution -- find definitions, references, and implementations
• Project-aware context -- understands your project structure and dependencies
• File operations -- read, write, and modify files with full context
• Git integration -- view diffs, stage changes, and understand version history

Feature	Serena	Basic File MCP	IDE Extension
File read/write	Yes	Yes	Yes
Semantic code navigation	Yes	No	Yes
Symbol lookup	Yes	No	Yes
Cross-file references	Yes	No	Yes
Works with any MCP client	Yes	Yes	No
Language support	Via LSP servers	N/A	Single IDE
Open source	Yes	Varies	Varies

Prerequisites

Before installing Serena, make sure you have:

• Python 3.10+ installed
• uv (Python package manager) or pip
• A supported LSP server for your language (see language setup below)
• An MCP-compatible client (Claude Desktop, Cursor, Claude Code, etc.)

Installation

Method 1: Install with uv (Recommended)

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the Serena repository
git clone https://github.com/oramasearch/serena.git
cd serena

# Create virtual environment and install dependencies
uv sync

Method 2: Install with pip

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

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

pip install -e .

Method 3: Install via uvx (No Clone Required)

# Run directly without cloning
uvx --from git+https://github.com/oramasearch/serena.git serena

Project Configuration

Serena requires a project configuration file that tells it about your codebase and which LSP server to use.

Create a Project Config File

Create a .serena/config.yaml file in your project root:

# .serena/config.yaml

project_name: "my-project"
description: "A brief description of your project"

# Language server configuration
lsp:
  language: "typescript"
  command: "typescript-language-server"
  args: ["--stdio"]
  root_path: "."

# File patterns to include
include:
  - "src/**/*.ts"
  - "src/**/*.tsx"
  - "lib/**/*.ts"
  - "*.json"

# File patterns to exclude
exclude:
  - "node_modules/**"
  - "dist/**"
  - "build/**"
  - ".git/**"
  - "*.lock"

Language-Specific LSP Configurations

TypeScript / JavaScript

# Install the LSP server
npm install -g typescript-language-server typescript

lsp:
  language: "typescript"
  command: "typescript-language-server"
  args: ["--stdio"]

Python

# Install pyright
npm install -g pyright
# Or install python-lsp-server
pip install python-lsp-server

# Using Pyright
lsp:
  language: "python"
  command: "pyright-langserver"
  args: ["--stdio"]

# Or using pylsp
lsp:
  language: "python"
  command: "pylsp"

Rust

# Install rust-analyzer (usually included with rustup)
rustup component add rust-analyzer

lsp:
  language: "rust"
  command: "rust-analyzer"

Go

go install golang.org/x/tools/gopls@latest

lsp:
  language: "go"
  command: "gopls"

Java

lsp:
  language: "java"
  command: "jdtls"

Connecting to MCP Clients

Claude Desktop

Add Serena to your Claude Desktop MCP configuration file.

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "serena": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/serena",
        "serena",
        "--project-dir", "/path/to/your/project"
      ]
    }
  }
}

Restart Claude Desktop after editing the configuration.

Claude Code

Add Serena to your Claude Code MCP settings:

claude mcp add serena -- uv run --directory /path/to/serena serena --project-dir /path/to/your/project

Or add it to your .claude/settings.json:

{
  "mcpServers": {
    "serena": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/serena",
        "serena",
        "--project-dir", "/path/to/your/project"
      ]
    }
  }
}

Cursor

In Cursor, go to Settings > MCP Servers and add:

{
  "serena": {
    "command": "uv",
    "args": [
      "run",
      "--directory", "/path/to/serena",
      "serena",
      "--project-dir", "/path/to/your/project"
    ]
  }
}

Available MCP Tools

Once connected, Serena exposes these tools to your AI client:

Tool	Description
read_file	Read file contents with line numbers
write_file	Write or create files
list_directory	List files and directories
search_text	Search for text patterns across files
find_symbol	Find symbol definitions (functions, classes, variables)
get_references	Find all references to a symbol
get_definition	Go to symbol definition
get_hover_info	Get type information and documentation for a symbol
get_diagnostics	Get LSP diagnostics (errors, warnings)
git_diff	View git diff
git_log	View git history
git_stage	Stage files for commit

Example Usage

Once Serena is connected, you can ask your AI assistant things like:

• "Find all references to the UserService class across the project"
• "What is the type signature of the processPayment function?"
• "Show me all the diagnostics (errors and warnings) in the project"
• "Navigate to the definition of handleAuth and explain what it does"
• "Refactor the calculateTotal function to handle edge cases"

The AI can use Serena's semantic tools to navigate your codebase intelligently rather than doing naive text search.

Troubleshooting

LSP Server Not Starting

# Verify the LSP server is installed and accessible
which typescript-language-server  # Should return a path
typescript-language-server --stdio  # Should start without errors (Ctrl+C to exit)

Connection Issues with Claude Desktop

1. Check the config file is valid JSON (no trailing commas)
2. Verify paths are absolute, not relative
3. Check Claude Desktop logs: Help > Show Logs
4. Restart Claude Desktop after any config change

Serena Not Finding Symbols

• Make sure the LSP server supports your language features
• Check that your project's include patterns match your source files
• Verify the root_path points to the correct project directory
• Some LSP servers need a build step first (e.g., tsc --build for TypeScript)

Performance Issues

For large projects, optimize your configuration:

# Exclude heavy directories
exclude:
  - "node_modules/**"
  - "dist/**"
  - ".git/**"
  - "coverage/**"
  - "*.min.js"
  - "vendor/**"

# Limit to source files only
include:
  - "src/**/*.ts"
  - "src/**/*.tsx"

Serena vs. Other MCP Servers

Feature	Serena	filesystem MCP	GitHub MCP
File operations	Yes	Yes	Limited
LSP integration	Yes	No	No
Symbol navigation	Yes	No	No
Git integration	Yes	No	Yes
Remote repos	No	No	Yes
Setup complexity	Medium	Low	Low
Best for	Deep code analysis	Simple file access	GitHub workflows

Wrapping Up

Serena transforms how AI assistants interact with your code by providing semantic understanding through LSP integration. Instead of treating your codebase as flat text files, the AI can navigate definitions, find references, and understand types -- making it dramatically more useful for complex refactoring, debugging, and code review.

If you are building AI-powered applications that need media generation like images, video, and avatars, try Hypereal AI free -- 35 credits, no credit card required. It pairs well with any MCP-connected development workflow.