oraios/serena

What Serena does

Serena is an MCP server that supplies coding agents with the kinds of operations an IDE gives a human developer: symbol search, file outlines, reference lookup, rename, move, inline, symbolic edits, diagnostics and interactive debugging. Instead of asking an agent to read files and perform text surgery, it works at the symbol level through a language server.

The design is deliberately agent-first. High-level operations replace line-number and regex-oriented primitives, which matters most in large or multi-language codebases where context is expensive and text edits are fragile. Serena does not write code itself; an LLM client calls its tools and orchestrates the work.

Any MCP-capable client can use it, including terminal agents such as Claude Code, Codex, OpenCode and Gemini-CLI, IDE assistants in VS Code, Cursor and JetBrains products, and desktop or web clients. The server can be started by the client via a launch command or run independently in HTTP mode.

Quick start

Prerequisites: install uv; it is the only required dependency. Do not install Serena from an MCP or plugin marketplace, because those listings may contain outdated commands.

Install the package:

uv tool install -p 3.13 serena-agent

Confirm that the serena command is available, then initialise:

serena init

This configures the language-server backend by default and should print a success message. To use the paid JetBrains backend instead, run serena init -b JetBrains and install the Serena plugin.

The remaining step is client configuration: add a launch command that starts the Serena MCP server, or run the server in HTTP mode and give the client its URL. Client-specific instructions are in the client setup guide. A short video introduction covers the overall flow.

After connecting, open a project in your agent and ask it to explore or refactor code; Serena's tools should appear in the client's tool list.

Language backends and coverage

Two backends provide the semantic capabilities:

• Language servers (default, open source). The LSP layer covers more than 40 languages, including Python, TypeScript, Java, Go, Rust, C/C++, C#, Ruby, PHP and many others. Some language servers require extra dependencies per language; see the language support page. Rename only applies to symbols, and find-declaration/find-implementations have limits imposed by the language server.
• JetBrains plugin (paid, free trial). It uses the analysis engine of IntelliJ-based IDEs and adds capabilities the LSP path lacks: search in dependencies, type hierarchy, move (symbols, files, directories), inline, deletion propagation, and REPL-style interactive debugging. Rider and CLion are not supported. See the plugin documentation.

The capability differences matter when choosing a backend: renaming files and directories, removing unused code after refactors, and setting breakpoints are JetBrains-only.

Configuration and workflow

Serena ships basic file, search and shell tools, but these are typically disabled by default inside agent harnesses such as Claude Code or Codex, because the harness already provides equivalent functionality. Keep the semantic tools enabled and let the harness handle plain file operations.

A memory system supports long-lived agent workflows by persisting knowledge across sessions, users and projects; it can be combined with files like AGENTS.md or disabled. Active tools, tool descriptions, prompts and backend settings are configurable through layered YAML: global, launch-command, per-project with local overrides, execution-context, and composable mode fragments. The user guide and configuration reference describe these layers, and the project workflow page covers how Serena expects projects to be opened and used.

Constraints and licensing

• Serena is a tool provider, not an autonomous agent: it needs an MCP/LLM client to drive it.
• Python 3.13 is specified in the install command; uv manages the environment.
• Language coverage and semantic accuracy depend on the chosen language server, and external-dependency declarations may not resolve under LSP.
• Licensing is per component: SolidLSP (src/solidlsp) is MIT, while the rest of the application is GPL-3.0-or-later. Combined distributions are subject to the GPL as a whole; see the license overview and license documentation. Contributions require accepting the CLA.

HotRepo's take

The project has substantial traction: about 30,969 stars and 2,118 forks, and it appeared on the Python daily ranking at position 14 on 2026-11-01 with 57 stars gained that day. It also drew early attention on Hacker News in April 2025, where a commenter involved with the project described the approach as replacing RAG with a language server to analyze code, and noted that it runs as an MCP server usable with Claude Desktop without an API key or subscription (comment by MischaPanch, 2025-04-03).

The README's own evaluation quotes agents claiming large savings on cross-file renames and reference lookups; that is vendor-published material rather than an independent benchmark. The more concrete differentiator is architectural: using LSP for semantics, and offering a paid JetBrains backend for operations LSP cannot do. Teams already using Claude Code or Codex should treat Serena as a semantic upgrade layer over their existing harness, not a replacement client.