# Serena

Canonical: https://cqbase.net/zh/entry/serena
Chinese: https://cqbase.net/zh/entry/serena
English: https://cqbase.net/en/entry/serena

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

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

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

推荐来源：

- [@HermesWatcher](https://x.com/HermesWatcher/status/2115081092118032871) 在 2026 年 10 月 27 日 的帖子里提到了这个项目（数字采集于 2026 年 11 月 15 日：1149 次喜欢，126 次转发）。
- [@stewy0x](https://x.com/stewy0x/status/2121586834232758521) 在 2026 年 11 月 14 日 的帖子里提到了这个项目（数字采集于 2026 年 11 月 15 日：52 次喜欢，7 次转发）。
- [@skizzyy2](https://x.com/skizzyy2/status/2120856666451083515) 在 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](https://oraios.github.io/serena/01-about/020_programming-languages.html)。

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

## 怎么装

核验日期为 2026-11-15（Asia/Shanghai）。命令来自仓库 [README](https://github.com/oraios/serena) 和官方 [Connecting Your MCP Client](https://oraios.github.io/serena/02-usage/030_clients.html)。

官方用显著提示写明：不要通过 MCP 或插件市场安装 Serena，那些地方的命令往往过时或并不合适。唯一的前置依赖是安装 [uv](https://docs.astral.sh/uv/getting-started/installation/)。然后执行：

```bash
uv tool install -p 3.13 serena-agent
```

装好后，终端里应能直接运行 `serena`。再执行初始化：

```bash
serena init
```

默认会启用语言服务器后端。若改用 JetBrains 后端，官方写法是加上 `-b JetBrains`，并参阅 [插件说明](https://oraios.github.io/serena/02-usage/025_jetbrains_plugin.html)。

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

**Claude Code**

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

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

只给当前项目启用时，可用：

```bash
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`，参数为：

```text
start-mcp-server --context ide
```

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

**Claude Desktop**

在 Settings → Developer 中编辑 `claude_desktop_config.json`：

```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](https://github.com/oraios/serena/issues/2251)（2026-11-15 仍为 open）还报告过 `serena-hooks remind` 会直接拦住工具调用，而不只是提醒。若启用 hooks，请阅读当前文档并观察实际行为。
- 启动超时。官方提到可提高 `MCP_TIMEOUT`。[issue #2270](https://github.com/oraios/serena/issues/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](https://github.com/oraios/serena/blob/main/LICENSE) 和 [许可说明](https://oraios.github.io/serena/01-about/060_license.html)。本文只做摘要并附上链接；商用或再分发前请自行判断。

### Cursor 要不要加 --context ide？

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

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

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

## 来源与许可

仓库 [oraios/serena](https://github.com/oraios/serena) 的许可证在本站条目中记为 unspecified。官方文档的说明见 [LICENSE](https://github.com/oraios/serena/blob/main/LICENSE) 与 [许可文档](https://oraios.github.io/serena/01-about/060_license.html)。本文依据 2026-11-15 查阅的 README 和 [客户端接入文档](https://oraios.github.io/serena/02-usage/030_clients.html)，用自己的话写成，供 CQBase 上下文库使用。若安装命令或客户端参数有变，以这些官方材料为准。

## 收录信息

- 作者: oraios
- 许可证: 未明确
- 来源: https://github.com/oraios/serena
- 收录: 2026-11-15
- GitHub 星标: 31391（采集 2026-11-15）

