# Serena MCP - Complete Installation & Usage Guide

**Date:** 2025-10-09  
**Status:** Production-ready FOSS project  
**GitHub:** https://github.com/oraios/serena  
**Stars:** 9.8k+ (very active!)

---

## 🎯 What is Serena?

**Serena** is a FREE, open-source MCP server that makes AI assistants (Claude, Cursor, etc.) WAY smarter at coding by giving them **semantic code understanding** - not just text reading.

### The Problem Serena Solves

**Without Serena:**
- AI reads your ENTIRE codebase every time (wastes tokens 💸)
- AI only sees text, not code structure (like class relationships, function calls)
- Large projects hit token limits fast
- AI can't find specific functions/classes efficiently

**With Serena:**
- AI reads ONLY what it needs (70% token savings! 🎉)
- AI understands code semantically (via Language Server Protocol)
- AI can search by meaning: "find all authentication functions"
- Creates project "memories" in `.serena/memories/` for context
- Works like a real IDE with symbol navigation, references, etc.

### How It Works

1. **First run (Onboarding):**
   - Serena scans your project
   - Creates index of all code symbols (classes, functions, etc.)
   - Generates "memory" files in `.serena/memories/` with project understanding
   - Starts language servers (Python, TypeScript, Java, etc.)

2. **During conversation:**
   - AI asks Serena specific questions like "find_symbol", "get_references"
   - Serena uses language servers to get exact answers
   - Only relevant code is sent to AI (not the whole project)
   - AI has semantic understanding (not just text search)

3. **Automatic optimization:**
   - Serena caches results
   - Updates indexes when files change
   - Manages memory files automatically

---

## 📋 Supported Languages

**Fully Supported (Auto-configured):**
- Python (pylsp)
- JavaScript/TypeScript (typescript-language-server)
- Rust (rust-analyzer)
- Go (gopls)
- Java, C#, C++, and 8+ more

**Works Best For:**
- Large projects (10,000+ lines)
- Multi-file codebases with complex relationships
- Projects with good structure (not single-file scripts)

---

## 🔧 Installation Guide

### Prerequisites

**Required:**
- Python 3.10+ (you have 3.13 ✅)
- `uv` package manager (Python's new fast package tool)

**Install uv (Windows PowerShell):**
```powershell
# Run this command
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Verify installation
uv --version
```

**Or via winget:**
```powershell
winget install astral-sh.uv
```

---

## 🚀 Quick Setup (Recommended Method)

### Method 1: Direct Run (No Clone Needed) ⭐ EASIEST

This uses `uvx` to run Serena directly from GitHub:

**For Claude Desktop:**

1. Open Claude Desktop config:
   ```
   C:\Users\sandr\AppData\Roaming\Claude\claude_desktop_config.json
   ```

2. Add Serena entry:
   ```json
   {
     "mcpServers": {
       "serena": {
         "command": "uvx",
         "args": [
           "--from",
           "git+https://github.com/oraios/serena",
           "serena",
           "start-mcp-server",
           "--context",
           "ide-assistant"
         ],
         "env": {
           "PYTHONUNBUFFERED": "1"
         }
       }
     }
   }
   ```

3. Restart Claude Desktop **completely** (quit from system tray!)

4. Verify: Look for hammer icon 🔨 next to your message box

**For Cursor:**

1. Open/create Cursor MCP config:
   ```
   C:\Users\sandr\.cursor\mcp.json
   ```

2. Add Serena entry:
   ```json
   {
     "mcpServers": {
       "serena": {
         "command": "uvx",
         "args": [
           "--from",
           "git+https://github.com/oraios/serena",
           "serena",
           "start-mcp-server",
           "--context",
           "ide-assistant"
         ]
       }
     }
   }
   ```

3. Restart Cursor

---

### Method 2: Clone & Run (More Control)

**For Sandra's setup:**

```powershell
# Navigate to repos
Set-Location "d:\dev\repos"

# Clone Serena
git clone https://github.com/oraios/serena
Set-Location "d:\dev\repos\serena"

# Test it works
uv run serena start-mcp-server --help
```

**Claude Desktop config:**
```json
{
  "mcpServers": {
    "serena": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "d:\\dev\\repos\\serena",
        "serena",
        "start-mcp-server",
        "--context",
        "ide-assistant"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}
```

---

## 🎮 Using Serena

### First Time in a Project

When you start working on a project, Serena needs to "onboard":

**In Claude/Cursor, say:**
```
"Run onboarding for this project"
```

Or just start coding naturally:
```
"Analyze the authentication flow in this project"
```

Serena will:
1. Scan your project structure
2. Create `.serena/memories/` folder
3. Generate memory files (project structure, key components, etc.)
4. Index all code symbols
5. Start language servers

**This takes 30 seconds to 2 minutes** depending on project size.

### After Onboarding

Serena is ready! It has deep understanding of your code.

**What You Can Ask:**

**Code Navigation:**
```
"Find all functions that handle user authentication"
"Show me where UserService is defined"
"Find all references to the authenticate() method"
"List all classes in the auth module"
```

**Code Analysis:**
```
"Explain the relationship between UserController and UserService"
"What does the payment processing flow look like?"
"Find potential security issues in the login code"
"Analyze code complexity in the database layer"
```

**Code Editing:**
```
"Add logging to all API endpoints"
"Refactor the UserService to use dependency injection"
"Fix all TODO comments in the project"
"Add error handling to database queries"
```

**Project Understanding:**
```
"What does this project do?"
"Where is the main entry point?"
"How is authentication implemented?"
"Show me the API structure"
```

### Serena's Tools (What It Can Do)

Serena provides these tools to the AI:

- `get_symbol_definition` - Get code for a specific symbol
- `get_symbol_references` - Find all uses of a symbol
- `search_symbols` - Search for symbols by name/pattern
- `find_patterns` - Search code by regex pattern
- `list_memories` - Show available memory files
- `read_memory` - Read a memory file
- `read_file` - Read any project file
- `replace_lines` - Edit code by line ranges
- `replace_symbol_body` - Replace entire function/class
- `list_dir` - Browse project structure
- `onboarding` - Initialize project understanding
- `prepare_for_new_conversation` - Continue with context

**You don't call these directly!** The AI decides when to use them.

---

## 📊 The Dashboard (Very Cool!)

Serena runs a **local web dashboard** for monitoring:

**Access:** http://localhost:24282/dashboard/index.html

**Shows:**
- All tool calls Serena makes
- Language server status
- Project memory files
- Token usage estimates
- Real-time logs

**Auto-opens** when you start Serena (unless disabled)

---

## ⚙️ Configuration

### Project Config (.serena/serena_config.yml)

After first run, edit `.serena/serena_config.yml` in your project:

```yaml
# Ignore certain directories (important!)
ignored_dirs:
  - node_modules
  - .venv
  - venv
  - __pycache__
  - dist
  - build
  - .git

# Read-only mode (no editing)
read_only: false

# Disable dangerous shell commands
disabled_tools:
  - execute_shell_command

# Language-specific settings
languages:
  python:
    language_server: "pylsp"
  typescript:
    language_server: "typescript-language-server"
```

### Contexts (Behavior Modes)

Serena has different "contexts" for different use cases:

- `desktop-app` - Default for Claude Desktop
- `ide-assistant` - Best for Cursor/IDEs (recommended)
- `agent` - For autonomous operation
- `planning` - Focus on analysis
- `editing` - Optimize for code changes

**Set context in config:**
```json
"args": [
  "serena",
  "start-mcp-server",
  "--context",
  "ide-assistant"
]
```

---

## 🛡️ Safety & Best Practices

### Critical Warnings

1. **Backup your work!** Serena can edit code.
   - Use git: `git add -A && git commit -m "before serena"`

2. **Inspect commands:** When Serena wants to run shell commands, CHECK THEM!

3. **Use read-only mode** if you only want analysis:
   ```yaml
   read_only: true
   ```

4. **Ignore large folders:** Add to `ignored_dirs` or it will scan forever:
   ```yaml
   ignored_dirs:
     - node_modules
     - .venv
     - data
     - logs
   ```

### Known Issues

**Serena hangs on startup:**
- Usually due to large virtual environments
- **Fix:** Add venv folders to `ignored_dirs`
- **Fix:** Delete `.serena/` folder and restart

**Language server not starting:**
- Check Serena dashboard logs
- Serena auto-installs servers, but might fail
- **Fix:** Manually install (e.g., `pip install python-lsp-server`)

**Token limits hit:**
- Serena helps but doesn't eliminate limits
- **Fix:** Use more focused prompts
- **Fix:** Work on smaller modules at a time

---

## 📈 Performance Tips

### Maximize Token Savings

1. **Good project structure:**
   - Well-organized folders
   - Clear naming conventions
   - Serena navigates better = fewer tokens

2. **Use memories:**
   ```
   "Read the memories for this project first"
   ```
   Then ask your question

3. **Specific prompts:**
   ```
   ❌ "Improve this project"
   ✅ "Refactor the UserService class to use interfaces"
   ```

4. **Let Serena prepare:**
   ```
   "Run prepare_for_new_conversation"
   ```
   Before starting new chat

### Speed Up Onboarding

- Configure `ignored_dirs` BEFORE first run
- Start with smaller modules
- Use `.gitignore` (Serena respects it)

---

## 💡 Real-World Examples

### Example 1: Bug Hunting

```
You: "Find all database queries that don't have error handling"
Serena: *searches symbols, analyzes code*
Serena: "Found 5 instances in UserRepository, OrderRepository..."

You: "Add try-catch blocks to all of them"
Serena: *edits files with replace_symbol_body*
```

### Example 2: Refactoring

```
You: "The UserService class is too large. Split it into UserAuthService and UserProfileService"
Serena: *analyzes dependencies, creates new files, updates imports*
```

### Example 3: Understanding New Project

```
You: "I just inherited this codebase. Explain the architecture"
Serena: *reads memories, analyzes structure*
Serena: "This is a 3-tier architecture with..."
```

---

## 🎓 Advanced Usage

### Custom Memory Files

You can manually add memory files to `.serena/memories/`:

**Example:** `.serena/memories/deployment.md`
```markdown
# Deployment Process

1. Run tests: npm test
2. Build: npm run build
3. Deploy: ./deploy.sh production

Database migrations run automatically.
```

Serena will read this when relevant!

### Multiple Projects

Each project gets its own `.serena/` folder with separate:
- Memory files
- Index
- Configuration

You can copy memory files between projects for consistency.

### Integration with Claude Code

**Claude Code CLI** has special Serena integration:

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

This automatically configures Serena for the current directory!

---

## 🔧 Troubleshooting

### Serena Not Showing Up

**Check:**
1. Config file syntax is valid JSON
2. You fully restarted the IDE (not just closed window!)
3. Look for hammer icon 🔨 in chat
4. Check IDE logs for MCP errors

**Claude Desktop logs:**
```
C:\Users\sandr\AppData\Roaming\Claude\logs\
```

**Cursor logs:**
```
%APPDATA%\Cursor\logs\
```

### Serena Hangs on Startup

**Common causes:**
- Scanning large `node_modules` or `venv`
- Too many files

**Fixes:**
1. Add to `.gitignore` (Serena respects it)
2. Configure `ignored_dirs` in `serena_config.yml`
3. Delete `.serena/` and restart

### Commands Not Working

**Try:**
```
"Use the onboarding tool"
"Use the find_symbol tool to search for UserService"
```

Be explicit about tool names!

### Out of Context Errors

Even with Serena, you can hit limits on huge files.

**Solutions:**
- Work on smaller modules
- Split large files
- Use focused prompts
- Start new conversation with `prepare_for_new_conversation`

---

## 📝 Summary: Serena Cheat Sheet

**Installation:**
```powershell
# Quick method
Add to claude_desktop_config.json:
{
  "serena": {
    "command": "uvx",
    "args": ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--context", "ide-assistant"]
  }
}
```

**First Use:**
```
"Run onboarding for this project"
```

**Common Commands:**
```
"Find all functions that..."
"Show me where X is defined"
"Refactor X to use Y"
"Explain the architecture"
"Add logging to all endpoints"
```

**Dashboard:**
```
http://localhost:24282/dashboard/index.html
```

**Memory Location:**
```
<your-project>/.serena/memories/
```

**Config:**
```
<your-project>/.serena/serena_config.yml
```

---

## 🎯 Is Serena Right for You?

**YES, if:**
- ✅ Working on medium/large projects (1000+ lines)
- ✅ Multi-file codebases with structure
- ✅ Want to save tokens/API costs
- ✅ Need semantic code understanding
- ✅ Projects in Python, JS/TS, Java, Rust, Go

**MAYBE NOT, if:**
- ❌ Single-file scripts
- ❌ Very small projects (<100 lines)
- ❌ Just need basic text editing
- ❌ Don't want to manage another tool

---

## 🔗 Resources

- **GitHub:** https://github.com/oraios/serena
- **Issues:** https://github.com/oraios/serena/issues
- **Changelog:** https://github.com/oraios/serena/releases
- **Roadmap:** Check GitHub discussions

---

**Built by:** Oraios AI  
**License:** MIT (Free Open Source)  
**Status:** Active development, 9.8k+ stars, production-ready

---

**Try it!** It's free, open source, and can save you 70% of tokens. What's not to love? 🚀