Serena: An MCP Server That Gives AI Coding Agents IDE-Level Symbol Awareness

Why Line Numbers Are the Wrong Abstraction for AI Code Agents

When an AI agent edits a file using line numbers, it operates on a brittle reference. A single insertion anywhere above the target line invalidates every stored position. The agent must re-read the file, recalculate offsets, and verify no concurrent change has shifted things. Serena takes a different approach by providing tools that work at the symbol level: named functions, classes, methods, and their references, rather than on character offsets.

The README describes this as agent-first tool design with high-level abstractions that distinguish it from approaches relying on low-level concepts like line numbers or primitive search patterns. Cross-file renames, reference lookups, and symbol moves are atomic tool calls in Serena's interface. The README quotes an evaluation by an Opus 4.6 agent on a large Python codebase: cross-file renames and reference lookups that would require eight to twelve careful steps collapse into one atomic call.

Serena connects to any LLM client that supports the Model Context Protocol (MCP). The README lists supported clients including Claude Code, Codex, Gemini-CLI, Cursor, JetBrains IDE plugins, Claude Desktop, and OpenWebUI. The MCP server can be started by the client via a launch command, or run in HTTP mode on a fixed URL that the client connects to.

Two Analysis Backends: Language Servers and the JetBrains Plugin

Serena supports two distinct code analysis backends. The default is a set of language server integrations. The Language Server Protocol (LSP) is an open standard that decouples editor intelligence from editor implementation, and Serena's abstraction layer connects to language servers for over 40 programming languages. The README lists them in full, covering Ada, C/C++, C#, Clojure, Dart, Elixir, Erlang, F#, Go, Haskell, Java, JavaScript, Kotlin, Lua, OCaml, Pascal, Perl, PHP, Python, R, Ruby, Rust, Scala, Swift, TypeScript, YAML, Zig, and more.

The alternative backend is the Serena JetBrains Plugin. This is a paid plugin available from the JetBrains Plugin Marketplace, with a free trial. It uses the code analysis engine of an installed JetBrains IDE, including IntelliJ IDEA, PyCharm, WebStorm, GoLand, Android Studio, and JetBrains AI Assistant. The README explicitly notes that Rider and CLion are not supported by the plugin.

The choice between backends affects both cost and analysis depth. The language server backend is free and relies on open-source language servers. The JetBrains plugin adds a subscription cost but provides analysis at the IDE engine level for JetBrains-supported languages. The LSP backend is the default.

Connecting Serena to an AI Client and Running It in Docker

The README includes a prominent warning: do not install Serena through an MCP or plugin marketplace, as those sources contain outdated installation commands. The official Quick Start section in the repository's documentation is the authoritative source for the correct setup steps.

When running via Docker Compose, the repository's compose.yaml defines the Serena service and shows the server launch command:

uv run --directory . serena-mcp-server --transport sse --port 9121 --host 0.0.0.0

The MCP server listens on port 9121 and the Serena dashboard on port 24282, as shown in the port bindings in compose.yaml. To work with source code in the Docker setup, project directories must be mounted into the /workspace/ directory inside the container. The compose.yaml includes commented examples showing how to mount a project:

# volumes:
  # - ./my-project:/workspace/my-project
  # - /path/to/another/project:/workspace/another-project

The .env.example file in the repository shows two optional API key variables:

GOOGLE_API_KEY=<your_google_api_key>
ANTHROPIC_API_KEY=<your_key>

The Python package name in pyproject.toml is serena-agent and requires Python 3.11 or later (up to 3.14). The package version in the development tree is 2.0.0.dev0, indicating a pre-release development build.

Scope Limits and Where Serena Falls Short

Serena's tools are designed for code analysis and manipulation. The README describes them as covering semantic code retrieval, editing, refactoring, and debugging. Tasks outside structured code: parsing unstructured logs, analyzing images, or processing data files without code-level structure, are not part of Serena's tool set.

The Python package enforces a hard version floor. The `requires-python = ">=3.11, <3.15"` constraint in pyproject.toml means systems running Python 3.10 or earlier cannot install Serena at all. This is not a soft recommendation.

The LSP backend depends on external language server installations. Serena provides the integration and abstraction layer, but the underlying language servers are separate packages the user must install for each language they want to analyze. A codebase in a language without a locally installed language server receives no symbol-level analysis. The README documents support for over 40 languages without specifying which package names to install for each one.

Serena is licensed under GPL-3.0-or-later, which creates constraints for teams that distribute products incorporating it. Teams building internal tools are less affected, as the GPL does not require disclosure for private internal use. Commercial teams building distributed products should review the license implications before integrating Serena into a proprietary system.

GPL-3.0 License and Maintenance Status

The license is declared as GPL-3.0-or-later in pyproject.toml under the project metadata. The repository also includes a LICENSES/ directory, suggesting dual-licensing or separate license files for bundled components.

The last push to the main branch was on 2026-09-17. The most recent tagged release is v1.7.0, published on 2026-08-09. Earlier releases include v1.6.1 on 2026-07-21 and v1.6.0 on 2026-07-16, indicating a regular release cadence through mid-2026.

The pyproject.toml pins transitive dependencies at exact versions specifically to address Dependabot security alerts, with comments in the file explaining each pin. The repository ships a flake.nix for users in Nix-based development environments, a Docker setup with compose.yaml and a Dockerfile, and a CHANGELOG.md that tracks version history. The project includes a CONTRIBUTING.md and a CLA.md, indicating a formal contribution process with a Contributor License Agreement.

Editorial conclusion

Serena is a strong fit for engineering teams using MCP-compatible AI coding clients on medium-to-large codebases where symbolic operations (rename, find references, move symbol) need to be reliable and atomic. It is not the right tool for teams that need proprietary licensing terms, for projects in languages without available language servers, or for workflows where the AI acts primarily on non-code files. Before setting up Serena, verify that Python 3.11 or later is available on the server and that the language servers for your codebase's languages are installed, as Serena provides the integration layer but does not bundle the language servers themselves.

Frequently asked questions

Official sources

1. License: MIT
2. oraios/serena on GitHub
3. Project website
4. README
5. Releases