Server facts
Serena MCP Server
Project
- Author
- oraios
- Repository
- github.com/oraios/serena
- Website
- oraios.github.io/serena
- License
- MIT
- Category
- Developer Tools
Tech
- Runtime / language
- pythonPython
- Transports
- stdio
- Remote available
- No
- Authentication
- Not specified
Activity
- GitHub stars
- 30,329
- Last commit
- Data as of
Tags
- Coding Agents
- Jetbrains
- Language Server
- Refactoring
- Semantic Code
Overview
Serena extends coding assistants with operations based on symbols and relationships within a codebase. Rather than relying only on line numbers or text patterns, agents can inspect file outlines, locate symbols and references, replace symbol bodies, and perform supported refactorings. The project targets larger codebases where navigating structure is important to finding the right context. It also includes a configurable memory system for sharing knowledge across longer workflows. Serena supplies tools rather than an independent reasoning model: an existing LLM or client still decides what work to do and how to coordinate those tools.
Two backends provide semantic analysis. The default uses language servers and supports more than 40 languages, with some capabilities varying by server. An optional paid JetBrains plugin offers broader refactoring and dependency exploration, plus interactive debugging; Rider and CLion are listed as unsupported. Basic filesystem, regex, and shell utilities are also available, though agent harnesses may disable overlapping utilities by default. Setup uses uv to install serena-agent with Python 3.13, followed by initialization and client configuration. Clients can launch the MCP process or connect to a separately started HTTP server. Global, project, context, and mode settings let teams tailor active tools and prompts. The README warns against marketplace installation commands because those may be outdated.
Install & configure
Requirements
- uv
- An LLM client supporting MCP
- Additional language-specific dependencies where required
uv tool install -p 3.13 serena-agentThis command installs Serena; it is not the client launch command. Next run serena init, then configure your MCP client using the linked client guide. The default backend uses language servers. A separately started HTTP server is also supported, but no endpoint is stated in this README.
Examples are translated from the published configuration. Supply your own credentials and verify requirements in the upstream README. Remote connectors are shown only where a supported configuration format is known.
Config file · macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Use Settings → Developer → Edit Config when available. Do not assume a Linux configuration path; check the client documentation for your platform. Remote servers use the app’s connector flow when supported, not the local stdio file shown here. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"serena": {
"command": "uv",
"args": [
"tool",
"install",
"-p",
"3.13",
"serena-agent"
],
"env": {}
}
}
}Config file · Project: .cursor/mcp.json
User: ~/.cursor/mcp.json
The project path is relative to the workspace root. The tilde denotes your user home directory. Use Cursor’s MCP settings to confirm which configuration and scope your installed version is reading. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"serena": {
"command": "uv",
"args": [
"tool",
"install",
"-p",
"3.13",
"serena-agent"
],
"env": {}
}
}
}Config file · Workspace: .vscode/mcp.json
For user scope, use the “MCP: Open User Configuration” command if available. Do not guess a user configuration path across operating systems, profiles, containers, or remote workspaces; check the client documentation. Merge this example with existing settings; do not overwrite unrelated servers.
{
"servers": {
"serena": {
"type": "stdio",
"command": "uv",
"args": [
"tool",
"install",
"-p",
"3.13",
"serena-agent"
],
"env": {}
}
}
}Config file · macOS/Linux: ~/.codeium/windsurf/mcp_config.json
Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json
Open the MCP configuration through Windsurf’s settings when possible to confirm the active file. Paths can differ in managed or future releases; check the client documentation if this location is not present. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"serena": {
"command": "uv",
"args": [
"tool",
"install",
"-p",
"3.13",
"serena-agent"
],
"env": {}
}
}
}Config file · Project scope: .mcp.json at the repository root
The project file uses mcpServers. For user scope, use claude mcp add --scope user rather than assuming .mcp.json in your home directory is the user configuration. Check the client documentation for managed settings and storage details. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"serena": {
"type": "stdio",
"command": "uv",
"args": [
"tool",
"install",
"-p",
"3.13",
"serena-agent"
],
"env": {}
}
}
}Examples are translated from the published configuration. Supply your own credentials and verify requirements in the upstream README. Remote connectors are shown only where a supported configuration format is known.
Tools
Source: repository README. Tool descriptions are a documented snapshot, not a live capability check.
| Tool | What it does |
|---|---|
| search_for_pattern | Search a codebase using regular expressions. |
| replace_content | Apply literal or regex-based text substitutions. |
| list_dir | Inspect directory entries. |
| find_file | Locate files within a project. |
| read_file | Read complete files or selected portions. |
| execute_shell_command | Run shell tasks such as tests, builds, or linters. |
Names, permissions, and defaults can change. Check the current upstream documentation before granting access.
Use cases
- Navigate a large project using symbols, references, and file outlines.
- Edit symbol bodies and perform backend-supported refactorings.
- Preserve project knowledge across agent sessions with memory.
- Debug interactively through the optional JetBrains backend.
Strengths
- Provides symbol-aware alternatives to fragile text-only code manipulation.
- Supports more than 40 languages through its language-server backend.
- Offers layered configuration and optional persistent memory.
Limitations
- Semantic capabilities depend on the selected backend and language server.
- Interactive debugging and several advanced refactorings require the paid JetBrains plugin.
- Some languages need additional dependencies.
Frequently asked questions
Independent listing, not an affiliation or security review. Grant the least access needed and verify the upstream instructions before running code.
