nesbo/dotnet-claude-code-skills/add-serena

Add Serena MCP to Any Project

This skill helps you add Serena MCP (Model Context Protocol) to any software project, providing IDE-like semantic code understanding and navigation capabilities with true multi-project support.

What is Serena MCP?

Serena is a coding agent toolkit that provides:

• Language Server Protocol (LSP) integration for semantic code understanding
• Symbol-level navigation (find definitions, references, implementations)
• Precise code editing tools (insert after symbol, replace symbol body)
• Project-aware search and file operations
• Memory system for storing project-specific context
• Onboarding and project structure analysis

Supported languages: C#, Python, TypeScript, JavaScript, Go, Rust, Java, and more.

Multi-Project Philosophy

This skill enables you to add Serena to ANY project independently.

Key principles:

• Project-specific configuration - Each project has its own .mcp.json and .serena/ folder
• Complete isolation - Projects don't interfere with each other
• Separate memory and state - Each project maintains its own context
• No global installation - No hardcoded paths in ~/.claude.json
• Team-friendly - Configuration can be version controlled for team sharing

How it works:

1. You add Serena to Project A → Works in Project A
2. You add Serena to Project B → Works in Project B
3. Both projects maintain separate Serena instances with isolated state
4. You can work on multiple projects without reconfiguration

Prerequisites Check

Before adding Serena, verify:

1. uv (Python package manager) is installed

which uv
# Should return: /Users/nesbo/.local/bin/uv or similar

If not installed, see: https://github.com/astral-sh/uv

2. Python 3.11 is available

python3 --version
# Should show Python 3.11.x (Serena requires >=3.11, <3.12)

3. Language-specific requirements

• C#: Requires .sln file in project directory
• Python: Requires pyproject.toml or setup.py
• TypeScript/JavaScript: Requires tsconfig.json or package.json
• Go: Requires go.mod
• Rust: Requires Cargo.toml
• Java: Requires Maven or Gradle project file

4. Git repository (optional but recommended)

For .gitignore integration and version control benefits.

Installation Approach Overview

Per-Project Configuration with Helper Script

This approach creates three main components in your project:

1. `.mcp.json` - Tells Claude Code to load Serena MCP server for this project
2. `.serena/start-mcp.sh` - Portable helper script that auto-detects project root
3. `.serena/project.yml` - Project-specific Serena configuration

Benefits:

• ✅ Each project is self-contained and independent
• ✅ Completely portable across team members
• ✅ No manual path configuration needed
• ✅ Can be version controlled for team consistency
• ✅ Works reliably regardless of where you start Claude Code

Why helper script?

• MCP servers can't reliably detect current working directory when launched via uvx
• Helper script ensures Serena always knows the correct project root
• More portable than hardcoded absolute paths

Interactive Setup Guide

When using this skill, Claude Code will ask you several questions to customize the setup:

Question 1: Programming Language

"Which programming language is this project?"

Options: C#, Python, TypeScript, JavaScript, Go, Rust, Java, Other

This determines:

• Language server configuration in .serena/project.yml
• Which project files to look for (.sln, pyproject.toml, etc.)
• LSP features available

Question 2: Version Control

"Should Serena configuration be version controlled and committed to git?"

Option A: Yes, commit for team (Recommended for team projects)

• .mcp.json, .serena/start-mcp.sh, and .serena/project.yml are committed
• Entire team gets the same Serena setup
• No manual configuration per developer
• Best for: Team projects, shared codebases

Option B: No, keep it local (Recommended for personal tooling)

• Add Serena files to .gitignore
• Each developer configures independently
• Optional tooling, not required for the project
• Best for: Solo projects, experimental tools

Question 3: Permissions

"Should Serena tools be pre-approved?"

Option A: Yes, create settings.local.json with common tools

• Pre-approves frequently used Serena tools
• Less interactive prompting during use
• Still safe - only Serena tools are pre-approved
• Best for: Frequent Serena users

Option B: No, I'll approve interactively

• Claude Code prompts for each tool use
• More explicit control
• More clicking required
• Best for: Security-conscious users, occasional use

Installation Steps

Step 1: Navigate to Your Project

cd /path/to/your/project

Ensure you're in the project root directory where you want to add Serena.

Step 2: Use the add-serena Skill

In Claude Code, say:

Using the add-serena skill, add Serena MCP to my current project

or

@add-serena set up Serena for this project

Claude Code will then ask you the interactive questions (language, version control, permissions) and create all necessary files.

Step 3: Files Created

The skill creates the following structure:

your-project/
├── .mcp.json                      # MCP server configuration
├── .serena/
│   ├── start-mcp.sh              # Helper script (auto-detects project root)
│   └── project.yml               # Serena project configuration
└── .claude/
    └── settings.local.json       # Permissions (if you chose pre-approval)

.mcp.json

{
  "mcpServers": {
    "serena": {
      "command": "bash",
      "args": [".serena/start-mcp.sh"]
    }
  }
}

This tells Claude Code: "When running in this directory, start the Serena MCP server using the helper script."

.serena/start-mcp.sh

#!/bin/bash
PROJECT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context ide-assistant --project "$PROJECT_DIR"

This script:

• Auto-detects the project root directory
• Launches Serena with uvx (downloads and runs from GitHub)
• Passes the correct project path to Serena

.serena/project.yml

language: csharp  # or python, typescript, etc. based on your answer
ignore_all_files_in_gitignore: true
ignored_paths: []
read_only: false
excluded_tools: []
initial_prompt: ""
project_name: "YourProjectName"

Configuration options:

• language: Programming language for LSP integration
• ignore_all_files_in_gitignore: Respect .gitignore patterns
• ignored_paths: Additional paths to ignore
• read_only: If true, disables editing tools
• excluded_tools: List of tools to disable
• project_name: Human-readable project identifier

.claude/settings.local.json (Optional)

{
  "permissions": {
    "allow": [
      "mcp__serena__list_dir",
      "mcp__serena__find_file",
      "mcp__serena__get_symbols_overview",
      "mcp__serena__search_for_pattern",
      "mcp__serena__find_symbol",
      "mcp__serena__find_referencing_symbols",
      "mcp__serena__read_file",
      "mcp__serena__write_memory",
      "mcp__serena__read_memory",
      "mcp__serena__think_about_collected_information",
      "mcp__serena__onboard"
    ]
  }
}

Only created if you chose to pre-approve Serena tools.

Step 4: Update .gitignore

The skill will update (or create) .gitignore based on your version control choice:

If you chose to version control Serena config:

# Serena cache and state (project-specific, don't commit)
.serena/.cache/
.serena/.state/
.serena/memories/

If you chose NOT to version control:

# Serena MCP configuration (personal preference, not committed)
.mcp.json
.serena/
 
# Claude Code personal settings
.claude/settings.local.json

Step 5: Restart Claude Code

After the skill creates the files:

1. Exit Claude Code completely (Ctrl+C or exit command)
2. Navigate to your project directory:

``bash cd /path/to/your/project ``

1. Start Claude Code:

``bash claude . ` or `bash claude code ``

Step 6: Approve Project-Scoped MCP Server

When Claude Code starts, you'll see a prompt:

Project-scoped MCP server 'serena' found in .mcp.json
Do you want to enable this server?
- Always for this project
- Just this session
- Never

Choose "Always for this project" to avoid being asked again.

Security Note: Claude Code prompts for approval because project-scoped MCP servers can execute code. Only approve servers you trust.

Verification & Testing

Check MCP Server Status

Run the /mcp command in Claude Code:

/mcp

You should see:

MCP Servers:
- serena (project-scoped, enabled)

Test Basic Functionality

Try these commands to verify Serena is working:

1. List directory contents:

`` Use mcp__serena__list_dir to list files in src/ ``

1. Find a symbol:

`` Use mcp__serena__find_symbol to find the definition of MyClass ``

1. Search for pattern:

`` Use mcp__serena__search_for_pattern to search for "TODO" in the codebase ``

1. Onboard project:

`` Use mcp__serena__onboard to analyze the project structure ``

Verify Project Isolation

To confirm multiple projects work independently:

1. Add Serena to Project A
2. Add Serena to Project B
3. Start Claude Code in Project A - Serena should work
4. Start Claude Code in Project B - Serena should work independently
5. Check .serena/.state/ in each project - should be different

Available Serena Tools

Once configured, these tools are available through Claude Code:

File & Project Navigation

• mcp__serena__list_dir - List directory contents
• mcp__serena__find_file - Find files by pattern
• mcp__serena__read_file - Read file contents
• mcp__serena__search_for_pattern - Search for text patterns

Symbol-Level Code Understanding

• mcp__serena__get_symbols_overview - Get overview of symbols in a file
• mcp__serena__find_symbol - Find symbol definitions
• mcp__serena__find_referencing_symbols - Find all references to a symbol
• mcp__serena__get_document_symbols - Get all symbols in a document
• mcp__serena__get_symbol_definition - Get symbol definition

Code Editing (if read_only: false)

• mcp__serena__insert_after_symbol - Insert code after a symbol
• mcp__serena__replace_symbol_body - Replace symbol implementation
• mcp__serena__delete_symbol - Delete a symbol

Memory & Context

• mcp__serena__write_memory - Store project-specific information
• mcp__serena__read_memory - Retrieve stored information
• mcp__serena__think_about_collected_information - Analyze collected data

Project Understanding

• mcp__serena__onboard - Analyze and understand project structure

Decision Guides

Should I Version Control Serena Config?

Commit Serena config (.mcp.json, .serena/) when:

• ✅ Working on a team project
• ✅ Want all developers to have same tools
• ✅ Serena is essential to project workflow
• ✅ Want to onboard new developers faster
• ✅ Team agrees on using Claude Code + Serena

Gitignore Serena config when:

• ❌ Solo project or personal experimentation
• ❌ Team doesn't use Claude Code
• ❌ Serena is optional tooling, not required
• ❌ Developers have different tool preferences

Should I Pre-Approve Serena Tools?

Pre-approve (create settings.local.json) when:

• ✅ You trust Serena and use it frequently
• ✅ Want faster workflow with less clicking
• ✅ Comfortable with Serena's capabilities
• ✅ Project is your own or trusted team project

Approve interactively (skip settings.local.json) when:

• ❌ First time using Serena
• ❌ Want explicit control over each tool use
• ❌ Working on sensitive or unfamiliar codebase
• ❌ Prefer security through explicit approval