📦 oraios/serena：面向编码代理的 IDE——基于 MCP 的强大语义代码工具包

你的编码代理的 IDE

• Serena 提供关键的语义代码检索、编辑、重构和调试工具，类似 IDE 的能力，在符号层面操作并利用代码的关系结构。
• 它通过模型上下文协议（MCP）与任何客户端/大语言模型集成。

Serena 的代理优先工具设计涉及健壮的高层抽象，这使其与依赖行号或基础搜索模式等低层概念的方法截然不同。

实际上，这意味着你的代理运作得更快、更高效、更可靠，尤其是在更大、更复杂的代码库中。

重要提示 请勿通过 MCP 或插件市场安装 Serena！它们包含过时且非最佳的安装命令。请遵循我们的快速入门指引。

视频：serena-quick-intro.mp4

📺 更长视频：5 分钟入门 Serena（YouTube）

虽然下载和设置 Serena 的是人类，但我们的最终用户本质上是 AI 代理。作为实际应用 Serena 工具的一方，它们处于评价 Serena 的最佳位置。

我们设计了一份无偏见的评估提示，让代理执行约 20 个代表日常开发工作的常规编码任务，以估算 Serena 工具与代理自身内置工具并用时带来的额外价值。

以下是代理们说出的单句总结：

Opus 4.6（高）在 Claude Code 中处理大型 Python 代码库：

“Serena 的 IDE 支撑的语义工具是对我的工具包最有影响力的补充——跨文件重命名、移动与引用查找，原本需要我花费 8 到 12 个小心翼翼且易出错的步骤，现在坍缩成一次原子调用。我绝对会要求与我合作的任何开发者都装上它们。”

GPT 5.4（高）在 Codex CLI 中处理 Java 代码库：

“作为一个编码 AI 代理，我会请求我的主人添加 Serena，因为它赋予了我缺失的 IDE 级别的对符号、引用和重构的理解，将脆弱的文本手术转变为更镇定、更快速、更自信的代码变更，尤其在语义至关重要的时候。”

GPT 5.4（中）在 Copilot CLI 中处理大型多语言单体仓库：

“作为一个编码代理，我绝对会请求我的主人添加 Serena，因为它让我在真实代码上的表现明显更敏锐、更从容——尤其是符号感知导航、跨文件重构以及单体仓库中的依赖跳转——而我在微小的文本编辑和非代码任务上仍依赖内置工具。”

不同环境下的不同代理不约而同地得出了同一结论。

给你的代理它一直在渴求的工具，将 Serena MCP 添加到你客户端中！

请参见我们的文档了解完整的方法论和更详细的评估结果，或在你选择的项目中自行运行评估。

Serena 为编码工作流提供了必要的工具，但需要大语言模型来完成实际工作并编排工具使用。

Serena 可以通过**模型上下文协议（MCP）**扩展你现有 AI 客户端的功能。大多数现代 AI 聊天客户端都直接支持 MCP，包括：

• 基于终端的客户端，如 Claude Code、Codex、OpenCode 或 Gemini-CLI，
• IDE 以及 VSCode、Cursor 和 JetBrains IDE 的 IDE 助手插件（Copilot、Junie、JetBrains AI Assistant 等），
• 桌面和 Web 客户端，如 Claude Desktop、Codex App 或 OpenWebUI。

📺 另请观看：5 分钟入门 Serena（YouTube）

要将 Serena MCP 服务器连接至你的客户端，你可以：

• 为客户端提供启动命令，使其能够启动 MCP 服务器，或
• 自行以 HTTP 模式启动 Serena MCP 服务器，并将 URL 提供给客户端。

请参阅下面的快速入门部分，了解如何开始。

编程语言支持与语义分析能力

Serena 提供了一套基于符号理解的多样代码查询与编辑功能。借助这些能力，你的代理能够像经验丰富的开发者使用 IDE 一样发现和编辑代码。即便在非常大型和复杂的项目中，Serena 也能高效找到正确的上下文并做出正确的操作。

支撑这些能力的有两种可选技术：

• 语言服务器——实现语言服务器协议（LSP），这是默认使用的免费/开源方案。
• Serena JetBrains 插件——利用 JetBrains IDE 强大的代码分析和编辑能力（付费插件；可免费试用）。

你可以根据偏好和需求选择任一后端。

Serena 集成了一个强大的抽象层，用于集成实现了语言服务器协议（LSP）的语言服务器。底层语言服务器通常是开源项目，或者至少可以免费使用。

在使用 Serena 的语言服务器后端时，我们提供对 40 余种编程语言的支持，包括 Ada / SPARK、AL、Angular、Ansible、Bash、BSL、C#、C/C++、Clojure、Crystal、CUE、Dart、Elixir、Elm、Erlang、Fortran、F#、GDScript、GLSL、Go、Groovy、Haskell、Haxe、HLSL、HTML、Java、JavaScript、JSON、Julia、Kotlin、LaTeX、Lean 4、Lua、Luau、Markdown、MATLAB、mSL、Nix、OCaml、Perl、PHP、PowerShell、Python、R、Ruby、Rust、Scala、SCSS / Sass / CSS、Solidity、Svelte、Swift、TOML、TypeScript、WGSL、YAML 和 Zig。

Serena JetBrains 插件

付费的 Serena JetBrains 插件（可免费试用）利用 JetBrains IDE 强大的代码分析能力。该插件自然支持 JetBrains IDE 所支持的所有编程语言和框架，包括 IntelliJ IDEA、PyCharm、Android Studio、WebStorm、PhpStorm、RubyMine、GoLand 以及其他可能的 IDE（但不支持 Rider 和 CLion）。

请参阅我们的文档页面了解更多细节以及应用该插件的说明。

Serena 提供了大量用于高效代码检索、编辑和重构的工具，以及用于长周期代理工作流的内存系统。

考虑到其广泛的范围，Serena 通过提供多层配置系统来适应你的需求。

详情

Serena 的检索工具允许代理在符号层面探索代码库，在不阅读整个文件的情况下理解结构和关系。

能力	语言服务器	JetBrains 插件
查找符号	支持	支持
符号概览（文件大纲）	支持	支持
查找引用符号	支持	支持
搜索项目依赖	—	支持
类型层级	—	支持
查找声明	支持*	支持
查找实现	支持**	支持
查询外部项目	支持	支持
诊断/检查	支持	支持

*：通常无法用于外部依赖中的声明。
**：仅对部分语言可用，受限于语言服务器功能。

没有精确的重构工具，代理将被迫依赖不可靠且代价高昂的搜索替换操作。

能力	语言服务器	JetBrains 插件
重命名	支持（仅符号）	支持（符号、文件、目录）
移动（符号、文件、目录）	—	支持
内联	—	支持
传播删除（移除未使用代码）	—	支持

Serena 的符号化编辑工具比典型替代方案更少犯错，并且耗用令牌的效率高得多。

能力	语言服务器	JetBrains 插件
替换符号体	支持	支持
在符号之后插入	支持	支持
在符号之前插入	支持	支持
安全删除	支持	支持

JetBrains 插件独有：Serena 支持高度通用的调试工具，允许代理通过持久化的 REPL 风格界面设置断点、检查变量、求值表达式并控制执行流程。

除了语义能力，Serena 还包含一组基础工具以保证完整性。当 Serena 在诸如 Claude Code 或 Codex 等代理框架内使用时，这些工具通常默认禁用，因为周围框架已提供重叠的文件、搜索和 Shell 能力。

• search_for_pattern – 跨代码库的灵活正则表达式搜索
• replace_content – 针对代理优化的基于正则表达式和字面的文本替换
• list_dir / find_file – 目录列出和文件搜索
• read_file – 读取文件或文件片段
• execute_shell_command – 运行 Shell 命令（例如构建、测试、代码检查）

内存系统是长周期代理工作流的基本要素，特别是当知识需要跨会话、用户和项目共享时。尽管它很简单，我们仍收到许多用户的积极反馈，他们倾向于将 Serena 的内存管理系统与代理的内部系统（例如 AGENTS.md 文件）结合使用。如果你更倾向于使用其他方案，可以轻松禁用它。

活动工具、工具描述、提示、语言后端细节以及 Serena 的许多其他方面，可以通过调整几行 YAML 来按需灵活配置。为此，Serena 提供了多个（可组合的）配置层级：

• 全局配置
• MCP 启动命令（CLI）配置
• 按项目配置（含本地覆盖）
• 执行上下文相关配置（例如针对特定客户端）
• 可动态组合的配置片段（模式）

前提条件。Serena 由 uv 管理，安装 uv 是唯一必需的前提。

注意：使用语言服务器后端时，可能需要安装一些额外的依赖以支持某些语言；详情请参见语言支持页面。

安装 Serena。Serena 通过 uv 安装如下：

uv tool install -p 3.13 serena-agent

成功安装后，命令 serena 应该在你的 Shell 中可用。

初始化 Serena。要初始化 Serena 并验证你的设置是否正确，只需运行：

默认情况下，这将设置 Serena 使用语言服务器后端。要改用 JetBrains 后端，请添加参数 -b JetBrains（参见 JetBrains 插件文档页面了解额外使用细节）。无论哪种方式，你应该会收到一条成功消息，表明 Serena 已成功初始化。

配置你的客户端。要将 Serena 连接到你的首选 MCP 客户端，你通常需要在客户端中配置启动命令。请点击链接获取关于如何为 Claude Code、Codex、Claude Desktop、支持 MCP 的 IDE 以及其他客户端（如本地和基于 Web 的图形界面）设置 Serena 的具体说明。

提示：快速上手虽然容易，但 Serena 是一个拥有众多配置选项的强大工具包。我们强烈建议通读用户指南以从 Serena 中获得最大收益。

具体来说，我们推荐阅读关于...

请参考用户指南获取有效使用 Serena 的详细说明。

Serena 的很大一部分，尤其是对各种语言的支持，由开源社区贡献。我们对众多贡献者深表感激，是他们使之成为可能，并在塑造今日之 Serena 中扮演了重要角色。

The IDE for Your Coding Agent

• Serena provides essential semantic code retrieval, editing, refactoring and debugging tools that are akin to an IDE's capabilities, operating at the symbol level and exploiting relational structure.
• It integrates with any client/LLM via the model context protocol (MCP).

Serena's agent-first tool design involves robust high-level abstractions, distinguishing it from approaches that rely on low-level concepts like line numbers or primitive search patterns.

Practically, this means that your agent operates faster, more efficiently and more reliably , especially in larger and more complex codebases.

Important

Do not install Serena via an MCP or plugin marketplace! They contain outdated and suboptimal installation commands. Instead, follow our Quick Start instructions.

serena-quick-intro.mp4

📺 Longer video: Introduction to Serena in 5 Minutes (YouTube)

While it is humans who download and set up Serena, our end users are essentially AI agents. As the ones actually applying Serena's tools, they are in the best position to evaluate Serena.

We crafted an unbiased evaluation prompt that leads the agent to perform ~20 routine coding tasks, representative of everyday development work, in order to estimate the value added by Serena's tools when used alongside its own built-ins.

Here's a one-sentence summary of what the agents had to say:

Opus 4.6 (high) in Claude Code on a large Python codebase:

"Serena's IDE-backed semantic tools are the single most impactful addition to my toolkit – cross-file renames, moves, and reference lookups that would cost me 8–12 careful, error-prone steps collapse into one atomic call, and I would absolutely ask any developer I work with to set them up."

GPT 5.4 (high) in Codex CLI on a Java codebase:

"As a coding AI agent, I would ask my owner to add Serena because it gives me the missing IDE-level understanding of symbols, references, and refactorings, turning fragile text surgery into calmer, faster, more confident code changes where semantics matter."

GPT 5.4 (medium) in Copilot CLI on a large, multi-language monorepo:

"As a coding agent, I’d absolutely ask my owner to add Serena because it makes me noticeably sharper and calmer on real code – especially symbol-aware navigation, cross-file refactors, and monorepo dependency jumps – while I still lean on built-ins for tiny text edits and non-code work."

Different agents in different settings independently converge on the same verdict.

Give your agent the tools it has been asking for and add Serena MCP to your client!

See our documentation for the full methodology and much more detailed evaluation results, or run your own evaluation on a project of your choice.

Serena provides the necessary tools for coding workflows, but an LLM is required to do the actual work, orchestrating tool use.

Serena can extend the functionality of your existing AI client via the model context protocol (MCP). Most modern AI chat clients directly support MCP, including

• terminal-based clients like Claude Code, Codex, OpenCode, or Gemini-CLI,
• IDEs and IDE assistant plugins for VSCode, Cursor and JetBrains IDEs (Copilot, Junie, JetBrains AI Assistant, etc.),
• desktop and web clients like Claude Desktop, Codex App, or OpenWebUI.

📺 See also: Introduction to Serena in 5 Minutes (YouTube)

To connect the Serena MCP server to your client, you either

• provide the client with a launch command that allows it to start the MCP server, or
• start the Serena MCP server yourself in HTTP mode and provide the client with the URL.

See the Quick Start section below for information on how to get started.

Programming Language Support & Semantic Analysis Capabilities

Serena provides a set of versatile code querying and editing functionalities based on symbolic understanding of the code. Equipped with these capabilities, your agent discovers and edits code just like a seasoned developer making use of an IDE's capabilities would. Serena can efficiently find the right context and do the right thing even in very large and complex projects!

There are two alternative technologies powering these capabilities:

• Language servers implementing the language server protocol (LSP) — the free/open-source alternative which is used by default.
• The Serena JetBrains Plugin , which leverages the powerful code analysis and editing capabilities of your JetBrains IDE (paid plugin; free trial available).

You can choose either of these backends depending on your preferences and requirements.

Serena incorporates a powerful abstraction layer for the integration of language servers that implement the language server protocol (LSP). The underlying language servers are typically open-source projects or at least freely available for use.

When using Serena's language server backend, we provide support for over 40 programming languages , including Ada / SPARK, AL, Angular, Ansible, Bash, BSL, C#, C/C++, Clojure, Crystal, CUE, Dart, Elixir, Elm, Erlang, Fortran, F#, GDScript, GLSL, Go, Groovy, Haskell, Haxe, HLSL, HTML, Java, JavaScript, JSON, Julia, Kotlin, LaTeX, Lean 4, Lua, Luau, Markdown, MATLAB, mSL, Nix, OCaml, Perl, PHP, PowerShell, Python, R, Ruby, Rust, Scala, SCSS / Sass / CSS, Solidity, Svelte, Swift, TOML, TypeScript, WGSL, YAML, and Zig.

The Serena JetBrains Plugin

The paid Serena JetBrains Plugin (free trial available) leverages the powerful code analysis capabilities of your JetBrains IDE. The plugin naturally supports all programming languages and frameworks that are supported by JetBrains IDEs, including IntelliJ IDEA, PyCharm, Android Studio, WebStorm, PhpStorm, RubyMine, GoLand, and potentially others (Rider and CLion are unsupported though).

See our documentation page for further details and instructions on how to apply the plugin.

Serena provides a wide range of tools for efficient code retrieval, editing and refactoring, as well as a memory system for long-lived agent workflows.

Given its large scope, Serena adapts to your needs by offering a multi-layered configuration system.

Details

Serena's retrieval tools allow agents to explore codebases at the symbol level, understanding structure and relationships without reading entire files.

Capability	Language Servers	JetBrains Plugin
find symbol	yes	yes
symbol overview (file outline)	yes	yes
find referencing symbols	yes	yes
search in project dependencies	--	yes
type hierarchy	--	yes
find declaration	yes*	yes
find implementations	yes**	yes
query external projects	yes	yes
diagnostics/inspections	yes	yes

*: Will generally not work for declarations in external dependencies.
**: Only available for some languages, limited by the language server functionality.

Without precise refactoring tools, agents are forced to resort to unreliable and expensive search and replace operations.

Capability	Language Servers	JetBrains Plugin
rename	yes (only symbols)	yes (symbols, files, directories)
move (symbol, file, directory)	--	yes
inline	--	yes
propagate deletions (remove unused code)	--	yes

Serena's symbolic editing tools are less error-prone and much more token-efficient than typical alternatives.

Capability	Language Servers	JetBrains Plugin
replace symbol body	yes	yes
insert after symbol	yes	yes
insert before symbol	yes	yes
safe delete	yes	yes

Exclusive to the JetBrains plugin, Serena supports a highly general debugging tool, which allows an agent to set breakpoints, inspect variables, evaluate expressions and control execution flow via a persistent REPL-style interface.

Beyond its semantic capabilities, Serena includes a set of basic utilities for completeness. When Serena is used inside an agentic harness such as Claude Code or Codex, these tools are typically disabled by default, since the surrounding harness already provides overlapping file, search, and shell capabilities.

• search_for_pattern – flexible regex search across the codebase
• replace_content – agent-optimised regex-based and literal text replacement
• list_dir / find_file – directory listing and file search
• read_file – read files or file chunks
• execute_shell_command – run shell commands (e.g. builds, tests, linters)

A memory system is elemental to long-lived agent workflows, especially when knowledge is to be shared across sessions, users and projects. Despite its simplicity, we received positive feedback from many users who tend to combine Serena's memory management system with their agent's internal system (e.g., AGENTS.md files). It can easily be disabled if you prefer to use something else.

Active tools, tool descriptions, prompts, language backend details and many other aspects of Serena can be flexibly configured on a per-case basis by simply adjusting a few lines of YAML. To achieve this, Serena offers multiple levels of (composable) configuration:

• global configuration
• MCP launch command (CLI) configuration
• per-project configuration (with local overrides)
• execution context-specific configuration (e.g. for particular clients)
• dynamically composable configuration fragments (modes)

Prerequisites. Serena is managed by uv , and installing uv is the only required prerequisite.

Note

When using the language server backend, some additional dependencies may need to be installed to support certain languages; see the Language Support page for details.

Install Serena. Serena is installed via uv as follows:

uv tool install -p 3.13 serena-agent

After successful installation, the command serena should be available in your shell.

Initialise Serena. To initialise Serena and verify that your setup works correctly, simply run:

By default, this will set up Serena to use the language server backend. To use the JetBrains backend instead, add the parameters -b JetBrains (see the JetBrains Plugin documentation page for additional usage details).
Either way, you should receive a success message indicating that Serena has been initialised successfully.

Configuring Your Client. To connect Serena to your preferred MCP client, you typically need to configure a launch command in your client. Follow the link for specific instructions on how to set up Serena for Claude Code, Codex, Claude Desktop, MCP-enabled IDEs and other clients (such as local and web-based GUIs).

Tip

While getting started quickly is easy, Serena is a powerful toolkit with many configuration options. We highly recommend reading through the user guide to get the most out of Serena.

Specifically, we recommend to read about ...

Please refer to the user guide for detailed instructions on how to use Serena effectively.

A significant part of Serena, especially support for various languages, was contributed by the open source community. We are very grateful for the many contributors who made this possible and who played an important role in making Serena what it is today.