Serena is a powerful MCP server designed for advanced semantic code understanding and manipulation. It enables Claude to perform precise symbol-based operations—such as renaming, finding references, and extracting definitions—while maintaining persistent project memory across sessions. By moving beyond simple text search to true semantic awareness, Serena allows for reliable navigation and modification of large-scale codebases with high accuracy.

When should I use serena?

serena is useful in the following scenarios: • Safe Global Refactoring: Execute complex symbol renames across an entire project with semantic precision, ensuring all references are updated correctly without the risks of regex-based replacement. • Intelligent Code Navigation: Quickly locate symbol definitions, find all referencing call sites, and generate high-level overviews of file structures to master unfamiliar codebases rapidly. • Cross-Session Context Persistence: Utilize dedicated memory tools to store architectural insights, task progress, and project-specific knowledge that persists across different AI chat sessions. • Semantic Code Modification: Replace or insert code relative to specific symbols (classes, methods, functions) rather than line numbers, making automated edits more robust and context-aware. • Project Onboarding and Discovery: Use the onboarding and symbol overview features to systematically map out a new repository's logic and dependencies.

name	serena
description	Serena MCP usage guide for semantic code operations, symbol manipulation, project memory, and session persistence. Use when invoking any mcp__serena__* tools, performing symbol operations (rename, find references, extract), navigating large codebases, or managing project memory/sessions.

Serena MCP Server

Semantic code understanding with project memory and session persistence.

Required First Step

ALWAYS activate project before any Serena operation:

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_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

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

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

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

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

serena

When & Why to Use This Skill

Use Cases