MCP.so
Sign In

Serena MCP Server

@oraios

Basic information

Category

Developer Tools

Last updated

License

MIT

Transports

stdio

Author

oraios

About Serena MCP Server

A powerful MCP toolkit for coding, providing semantic retrieval and editing capabilities - the IDE for your agent

Before you connect

Documentation reviewed 2026-10-25

When to choose this server

Serena is useful for symbol-aware code navigation and editing. Its language-server or JetBrains backend provides code structure beyond plain text search.

Setup and limitations

The current upstream quick start installs serena-agent with uv, then runs serena init. It explicitly warns about outdated marketplace commands. Use the linked client guide and verify support for your programming language before copying an older configuration.

These notes check the linked documentation, not a live authenticated connection. Suggested checks are steps for you to run.

Serena MCP Server config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "serena": {
      "command": "uv",
      "args": [
        "tool",
        "install",
        "-p",
        "3.13",
        "serena-agent"
      ]
    }
  }
}

Serena MCP Server tools

Tool list not available yet

This listing does not currently have a tool list to display. This does not mean the server has no tools; check its documentation for supported capabilities.

We auto-extract tools from the README. The maintainer can list them under a ## Tools heading to populate this section.

Overview

What is Serena MCP Server?

Serena MCP is an open-source coding agent toolkit from Oraios that gives AI agents IDE-like semantic code retrieval, editing, refactoring and debugging tools, working at the symbol level instead of line numbers or plain text search.

Serena connects to any MCP client, such as Claude Code, Codex, Cursor, VS Code or Claude Desktop. Its analysis comes from one of two backends: free, open-source language servers (LSP, the default, covering 40+ languages) or the paid Serena JetBrains Plugin, which uses your JetBrains IDE's own code analysis (free trial available). The project describes itself as "the IDE for your coding agent", and it pays off most in large, complex codebases.

How to use Serena MCP Server?

The only prerequisite is uv. The maintainers advise against installing Serena through MCP or plugin marketplaces, which they say carry outdated install commands. Install and initialise it from your shell:

uv tool install -p 3.13 serena-agent
serena init

serena init sets up the language server backend by default. Add -b JetBrains to use the JetBrains plugin backend instead. Some languages need extra language-server dependencies (see the Language Support page in the docs).

Claude Code

The quickest route is serena setup claude-code. To add it by hand for all projects:

claude mcp add --scope user serena -- serena start-mcp-server --context claude-code --project-from-cwd

Or for the current project only:

claude mcp add serena -- serena start-mcp-server --context claude-code --project "$(pwd)"

Run /mcp to confirm the connection. If Serena starts too slowly, raise MCP_TIMEOUT (for example export MCP_TIMEOUT=60000). The docs also offer optional serena-hooks commands that remind the agent to use Serena's tools during long sessions.

Claude Desktop

Open File / Settings / Developer / MCP Servers / Edit Config and add:

{
  "mcpServers": {
    "serena": {
      "command": "serena",
      "args": ["start-mcp-server", "--context=desktop-app"]
    }
  }
}

Fully quit Claude Desktop (File / Exit) and reopen it.

VS Code

Run MCP: Add Server, pick Command (stdio) and enter serena start-mcp-server --context=vscode (global) or serena start-mcp-server --context=vscode --project ${workspaceFolder} (workspace).

Cursor

The docs have no Cursor-specific page. For MCP-enabled IDEs like Cursor, Windsurf, Cline and Roo Code, they suggest adding the serena start-mcp-server launch command with --context ide to reduce tool duplication.

Codex

Run serena setup codex, or add to ~/.codex/config.toml:

[mcp_servers.serena]
startup_timeout_sec = 15
command = "serena"
args = ["start-mcp-server", "--project-from-cwd", "--context=codex"]

Key features of Serena MCP Server

  • Symbol-level retrieval: find symbols, file outlines, referencing symbols, declarations and implementations.
  • Symbolic editing: replace a symbol body, insert before or after a symbol, and safe delete.
  • Refactoring: rename symbols with language servers. Move, inline and removing unused code need the JetBrains plugin.
  • Interactive debugging (JetBrains plugin only): breakpoints, variable inspection and expression evaluation through a persistent REPL.
  • Over 40 languages with the free LSP backend, including Python, TypeScript, Java, Go, Rust, C/C++ and C#.
  • A memory system for long-lived agent workflows that can be combined with files such as AGENTS.md, or turned off.
  • Layered YAML configuration (global, CLI, per project, per context and modes) to pick the active tools and prompts.
  • Serena v2 adds an optional REPL interface, where the agent runs Python against Serena's APIs to combine several operations in one call.

Serena MCP Server tools

Only a subset of tools is active in any configuration, chosen mainly by the --context you start Serena with.

  • Symbol tools: find_symbol, get_symbols_overview, find_referencing_symbols, find_declaration and find_implementations for navigation. replace_symbol_body, insert_after_symbol, insert_before_symbol, rename_symbol and safe_delete_symbol for edits. get_diagnostics_for_file returns diagnostics grouped by symbol.
  • JetBrains tools (optional): jet_brains_move, jet_brains_inline_symbol, jet_brains_type_hierarchy, jet_brains_run_inspections and jet_brains_debug.
  • File and shell tools: read_file, list_dir, find_file, search_for_pattern, replace_content and execute_shell_command. These are usually off inside harnesses like Claude Code that already have such tools.
  • Memory tools: write_memory, read_memory, list_memories, edit_memory and delete_memory.
  • Workflow and config tools: activate_project, onboarding, initial_instructions and get_current_config.

Use cases of Serena MCP Server

  • Navigate a large codebase by symbols: "Find every caller of parse_config and summarise how each one handles errors."
  • Make a cross-file rename in one atomic step instead of many search-and-replace edits.
  • Rewrite a single function: "Replace the body of UserService.create to validate the email first."
  • Follow dependencies across a multi-language monorepo with reference lookups.
  • Debug with the JetBrains plugin: set breakpoints, step through code and inspect variables from the agent.
  • Keep project notes between sessions with Serena's memories, or start a new repo with "Activate the current dir as project using serena."

Serena MCP Server vs alternatives

Serena's niche is semantic, symbol-aware code work. A general Filesystem MCP Server only reads and writes files, and documentation servers such as Context7 or DeepWiki supply library docs rather than editing your code. Within Serena, the free LSP backend covers navigation, symbolic edits and renames. The paid JetBrains plugin adds moves, inlining, type hierarchy and debugging.

Troubleshooting Serena MCP Server

  • Client cannot find the serena command: use the full path to the serena executable in your MCP config.
  • Tools load but the agent ignores them: set up the serena-hooks reminder hooks for Claude Code or VS Code, or prompt "Activate the current project with Serena and read initial instructions."
  • Startup timeout in Claude Code: raise MCP_TIMEOUT, for example to 60000.
  • Language server needs environment variables: GUI clients like Claude Desktop may not inherit your shell profile, so add an env block to the serena server entry.
  • Wrong project in global setups: in Codex, Claude Desktop or global VS Code configs, ask the agent to activate the current directory as the project at the start of each session.

Frequently asked questions

1

Is Serena MCP free?

Yes. The Serena application is open source under GPL-3.0-or-later (its SolidLSP component is MIT), and the default language server backend is free. Only the optional JetBrains plugin is paid, with a free trial.

2

Who maintains the Serena MCP server?

Oraios maintains Serena, with much of the language support contributed by the open-source community. The official repository is [oraios/serena](https://github.com/oraios/serena).

3

Does Serena work with Claude Code, Cursor and VS Code?

Yes. The docs give commands for Claude Code, VS Code, Codex, Claude Desktop, JetBrains assistants and others. Cursor uses the generic launch command, preferably with `--context ide`.

4

Do I need an API key?

No. Serena runs locally and needs no API key. The LLM is provided by your MCP client.

5

Which programming languages does Serena support?

With language servers, over 40 languages, including Python, Java, TypeScript, Go, Rust, C/C++, C#, PHP, Ruby and Kotlin. With the JetBrains plugin, any language your JetBrains IDE supports, except in Rider and CLion.

6

Can Serena run as a remote HTTP server?

Yes. You can start the Serena MCP server yourself in HTTP mode and give your client the URL, instead of letting the client launch it over stdio.

7

Is the Serena coding agent safe to use?

Serena can run shell commands and modify files. Its security model assumes your machine, client, repository and configuration are trusted, and the maintainers say sandboxing is the only way to fully guard against unintended actions.

8

Why should I not install Serena from an MCP marketplace?

The README warns that marketplace listings contain outdated install commands. Use `uv tool install -p 3.13 serena-agent` and the client commands from the official docs instead.

Comments

More Developer Tools MCP servers