Serena MCP Server

Semantic code understanding with project memory and session persistence.

Required First Step

ALWAYS activate project before any Serena operation:

code

mcp__serena__activate_project(project: "<path_or_name>")
mcp__serena__check_onboarding_performed()

When to Use Serena

Use Case	Serena	Alternative
Symbol rename with references	✅	❌ Morphllm
Find all references	✅	❌ Grep
Semantic code navigation	✅	❌ Native
Project memory/session	✅	❌ None
Pattern-based bulk edits	❌	✅ Morphllm
Simple text replacement	❌	✅ Edit tool

Core Tools

Project Lifecycle

•activate_project → REQUIRED FIRST - activate target project
•get_current_config → check active project and available tools
•check_onboarding_performed → verify project is ready
•onboarding → run if onboarding not yet performed

Symbol Operations

•find_symbol → locate symbols by name path pattern
•find_referencing_symbols → find all references to a symbol
•get_symbols_overview → high-level view of file symbols
•rename_symbol → rename across entire codebase
•replace_symbol_body → replace symbol definition
•insert_before_symbol / insert_after_symbol → add code around symbols

Search & Navigation

•search_for_pattern → regex search across codebase
•list_dir → list directory contents
•find_file → find files by mask

Memory Management

•write_memory → persist information for future sessions
•read_memory → retrieve stored information
•list_memories → show available memories
•edit_memory / delete_memory → modify or remove memories

Reflection (Call These!)

•think_about_collected_information → after search operations
•think_about_task_adherence → before code modifications
•think_about_whether_you_are_done → at task completion

Tool Details

See references/tools.md for detailed parameter documentation.

Workflow Patterns

Session Start

code

1. activate_project(project: "path/to/project")
2. check_onboarding_performed()
3. list_memories() → check existing context
4. read_memory("relevant_memory") → if applicable

Symbol Investigation

code

1. get_symbols_overview(relative_path: "file.py", depth: 1)
2. find_symbol(name_path_pattern: "ClassName", include_body: false)
3. find_symbol(name_path_pattern: "ClassName/method", include_body: true)
4. think_about_collected_information()

Symbol Modification

code

1. find_symbol(name_path_pattern: "target", include_body: true)
2. think_about_task_adherence()
3. replace_symbol_body(name_path: "target", relative_path: "file.py", body: "new code")

Cross-Session Persistence

code

1. write_memory("task_context", "important findings...")
2. [end session]
3. [new session]
4. activate_project(...)
5. list_memories()
6. read_memory("task_context")

Name Path Patterns

Pattern	Matches
`method`	Any symbol named "method"
`Class/method`	method inside Class
`/Class/method`	Exact path from file root
`Foo/get` with `substring_matching: true`	`Foo/getValue`, `Foo/getData`

Best Practices

•Activate first - Always activate_project before operations
•Read before edit - Use find_symbol with include_body: true before modifications
•Use reflection tools - Call think_about_* tools at appropriate points
•Prefer symbolic over text - Use symbol tools over grep/edit when possible
•Persist important context - Use memory for cross-session continuity