cqbase.net · 中英双语

CQBase 上下文库

Context & Query Base

MCP

Serena

面向编码代理的 MCP 工具集,强调语义检索和编辑,许可证未明确。

oraios/serena 被仓库说明为给编码代理用的 MCP 工具集,提供语义检索和编辑能力,作者把它比作“代理的 IDE”。GitHub 没有给出明确的 SPDX 许可证。

先在一个小仓库里看它索引了哪些符号、编辑范围有多大,再接到日常编码代理。许可证未明确,商用或再分发前要自行判断。不要把它指向你没有授权修改的代码。

推荐来源:

  • @HermesWatcher 在 2026 年 10 月 27 日 的帖子里提到了这个项目(数字采集于 2026 年 11 月 15 日:1149 次喜欢,126 次转发)。
  • @stewy0x 在 2026 年 11 月 14 日 的帖子里提到了这个项目(数字采集于 2026 年 11 月 15 日:52 次喜欢,7 次转发)。
  • @skizzyy2 在 2026 年 11 月 12 日 的帖子里提到了这个项目(数字采集于 2026 年 11 月 15 日:20 次喜欢,0 次转发)。

本页是导读,不是原文。

解决什么问题

Serena(仓库 oraios/serena)是给编码代理用的 MCP 工具集,强调在符号层面检索、编辑和重构代码,官方把它比作「代理的 IDE」。它默认通过语言服务器(LSP)理解代码;另外还有付费的 JetBrains 插件作为可选后端,并提供试用。

它本身不替代大模型,而是把工具交给已有的 MCP 客户端。官方列出的客户端包括 Claude Code、Codex、Claude Desktop,以及 VS Code、Cursor、JetBrains 一类 IDE。本文只写 MCP 路径。

适合谁

适合已经在用编码代理,并希望它按符号而不是按行号去查找和修改代码的人。官方说明语言服务器后端支持四十余种语言,具体语言和额外依赖见 Language Support。

请先在一个小仓库里看它索引了哪些符号、编辑范围有多大,再接到日常项目。不要把它指向你没有授权修改的代码。本站条目将许可证记为 unspecified,详见文末「来源与许可」。

怎么装

核验日期为 2026-11-15(Asia/Shanghai)。命令来自仓库 README 和官方 Connecting Your MCP Client。

官方用显著提示写明:不要通过 MCP 或插件市场安装 Serena,那些地方的命令往往过时或并不合适。唯一的前置依赖是安装 uv。然后执行:

uv tool install -p 3.13 serena-agent

装好后,终端里应能直接运行 serena。再执行初始化:

serena init

默认会启用语言服务器后端。若改用 JetBrains 后端,官方写法是加上 -b JetBrains,并参阅 插件说明。

若客户端找不到 serena 命令(即使它已在系统 PATH 里),官方建议在配置里改用可执行文件的绝对路径。部分语言服务器还需要额外环境变量;像 Claude Desktop 这类客户端可能不会继承 shell 配置文件里的变量,可以把它们写进 MCP 条目的 env 字段。

Claude Code

官方提供一条快捷命令 serena setup claude-code。手动安装时,用户级配置是:

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

只给当前项目启用时,可用:

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

用 /mcp 确认连接。若 Serena 启动太慢,官方建议提高 MCP_TIMEOUT,例如在 shell 配置里加上 export MCP_TIMEOUT=60000。官方还建议配置提醒类 hooks(标为 alpha),以减轻代理不用 Serena 工具的问题。本文不把它当作安装必做项。

Cursor

官方把 Cursor 与 Cline、Windsurf 等一并列在「MCP 启用的 IDE」下,并建议加上 --context ide,以减少与编辑器自带工具的重复。文档没有单独给出 Cursor 的 JSON 文件路径。在 Cursor 的 MCP 设置里新增一个 stdio 服务器时,命令为 serena,参数为:

start-mcp-server --context ide

若 Cursor 找不到命令,改用 serena 的绝对路径。

Claude Desktop

在 Settings → Developer 中编辑 claude_desktop_config.json:

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

官方提醒:必须用 File / Exit 完全退出 Claude Desktop,只关窗口常常只是最小化。重启后,聊天界面里应能看到 Serena 的工具(锤子图标)。Claude Desktop 使用全局配置,通常需要先让代理激活项目,例如「Activate the current dir as project using serena」。

一个实际例子

下面的提示词是为本文写的核验步骤,不是官方固定口令。本次没有在真实仓库里实跑,因此不编造符号列表。

  1. 在一个可丢弃的小仓库中完成 serena init,并按上一节接到客户端。
  2. 若客户端是全局配置,先发送:Activate the current directory as a Serena project. Do not edit any files.
  3. 再发送:Using Serena, find the definition of <a symbol you name> and list its references. Do not rename or replace anything.
  4. 请自己对照编辑器里的跳转结果。若代理只用内置的文本搜索,而没有调用 Serena 工具,先看官方的客户端说明,尤其是 Claude Code 关于 hooks 和工具偏好的部分。

常见坑

  • 从 MCP 或插件市场安装。官方 README 把它标为重要警告,认为那些命令过时且并不合适。请使用上面的 uv tool install 路径。
  • 客户端找不到 serena。官方把「改用绝对路径」列为常见问题。
  • 在 Claude Code 里,代理经常不用 Serena 的符号工具。官方将其部分归因为客户端的工具发现和模型对内置工具的偏好,并提供 hooks 以及 serena prompts print-cc-system-prompt-override。issue #2251(2026-11-15 仍为 open)还报告过 serena-hooks remind 会直接拦住工具调用,而不只是提醒。若启用 hooks,请阅读当前文档并观察实际行为。
  • 启动超时。官方提到可提高 MCP_TIMEOUT。issue #2270(仍为 open)还记录了 Windows 上 stdio 场景中激活命令超时的情况。
  • 把编辑范围开得太大。符号级替换、重命名和删除都是真实改动。先在小仓库里看清楚工具再用于日常分支。

FAQ

一定要装 JetBrains 插件吗?

不是。默认后端是语言服务器,官方写明这是免费、开源的路径。JetBrains 插件是付费选项,带有试用,并且支持一些语言服务器没有的能力(例如部分重构和交互式调试)。Rider 和 CLion 在官方说明里写为不支持。

为什么官方指定 Python 3.13?

当前 README 给出的安装命令是 uv tool install -p 3.13 serena-agent。本文没有在其他官方页面找到另一条互相冲突的最低版本声明。安装时请按这条官方命令来,而不是自行改成未写明的版本。

许可证到底是什么?

本站条目记为 unspecified,因为 GitHub 没有给出单一的 SPDX 标识。官方文档另有按组件说明的许可安排,请直接阅读仓库 LICENSE 和 许可说明。本文只做摘要并附上链接;商用或再分发前请自行判断。

Cursor 要不要加 --context ide?

官方对 Cursor 这类 IDE 客户端的建议是加上 --context ide,以减少工具重复。文档没有另给一份 Cursor 专用的完整 JSON 示例。若工具看起来重复或缺失,先核对启动参数里的 context。

全局配置和项目配置有什么差别?

官方区分得很清楚。VS Code、Claude Code 这类按工作区配置的客户端,通常应带上项目目录,并且不要中途切换项目。Claude Desktop 这类全局配置则需要先激活项目,activate_project 工具是必需的。

来源与许可

仓库 oraios/serena 的许可证在本站条目中记为 unspecified。官方文档的说明见 LICENSE 与 许可文档。本文依据 2026-11-15 查阅的 README 和 客户端接入文档,用自己的话写成,供 CQBase 上下文库使用。若安装命令或客户端参数有变,以这些官方材料为准。

订阅 CQBase 周刊

每周一封,介绍本周新收录的公开 AI 技能、提示词、MCP 和用法。可随时退订。我们不会把邮箱交给第三方作其营销之用。