Serena MCP Server

什么是 Serena MCP Server？

Serena MCP 是 Oraios 推出的开源编码智能体工具包，为 AI 智能体提供类似 IDE 的语义级代码检索、编辑、重构和调试工具，以符号为单位工作，而不是依赖行号或纯文本搜索。

Serena 可接入任何 MCP 客户端，例如 Claude Code、Codex、Cursor、VS Code 或 Claude Desktop。它的代码分析能力来自两种后端之一：免费开源的语言服务器（LSP，默认后端，支持 40 多种语言），或付费的 Serena JetBrains Plugin（使用 JetBrains IDE 自身的代码分析能力，提供免费试用）。项目自称“编码智能体的 IDE”，在大型、复杂的代码库中收益最明显。

如何使用 Serena MCP Server？

唯一的前置条件是 uv。维护者不建议通过 MCP 或插件市场安装 Serena，因为那里的安装命令已过时且不够理想。在终端中安装并初始化：

uv tool install -p 3.13 serena-agent
serena init

serena init 默认配置语言服务器后端；若要改用 JetBrains 插件后端，加上 -b JetBrains 参数。部分语言需要额外安装语言服务器依赖（见文档中的 Language Support 页面）。

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（例如 export MCP_TIMEOUT=60000）。文档还提供了可选的 serena-hooks 命令，用于在长会话中提醒智能体使用 Serena 的工具。

Claude Desktop

打开 File / Settings / Developer / MCP Servers / Edit Config，添加：

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

通过 File / Exit 完全退出 Claude Desktop 后再重新打开。

VS Code

运行 MCP: Add Server，选择 Command (stdio)，输入 serena start-mcp-server --context=vscode（全局）或 serena start-mcp-server --context=vscode --project ${workspaceFolder}（工作区）。

Cursor

文档没有 Cursor 专属页面。对于 Cursor、Windsurf、Cline、Roo Code 等支持 MCP 的 IDE，文档建议添加 serena start-mcp-server 启动命令并加上 --context ide，以减少工具重复。

Codex

运行 serena setup codex，或在 ~/.codex/config.toml 中添加：

[mcp_servers.serena]
startup_timeout_sec = 15
command = "serena"
args = ["start-mcp-server", "--project-from-cwd", "--context=codex"]

Serena MCP Server 的主要功能

• 符号级检索：查找符号、文件大纲、引用该符号的位置、声明和实现。
• 符号级编辑：替换符号主体、在符号前后插入内容、安全删除。
• 重构：通过语言服务器重命名符号；移动、内联和删除未使用代码需要 JetBrains 插件。
• 交互式调试（仅 JetBrains 插件）：通过持久的 REPL 设置断点、查看变量、计算表达式。
• 免费的 LSP 后端支持 40 多种语言，包括 Python、TypeScript、Java、Go、Rust、C/C++ 和 C#。
• 面向长期智能体工作流的记忆系统，可与 AGENTS.md 等文件配合使用，也可以关闭。
• 分层 YAML 配置（全局、CLI、项目、上下文和模式），用于选择启用的工具和提示词。
• Serena v2 新增可选的 REPL 接口：智能体通过运行 Python 调用 Serena 的 API，一次调用即可组合多个操作。

Serena MCP Server 工具

任何配置下都只会启用部分工具，主要由启动 Serena 时使用的 --context 决定。

• 符号工具：导航用的 find_symbol、get_symbols_overview、find_referencing_symbols、find_declaration、find_implementations；编辑用的 replace_symbol_body、insert_after_symbol、insert_before_symbol、rename_symbol、safe_delete_symbol；get_diagnostics_for_file 按符号分组返回诊断信息。
• JetBrains 工具（可选）：jet_brains_move、jet_brains_inline_symbol、jet_brains_type_hierarchy、jet_brains_run_inspections、jet_brains_debug。
• 文件与 Shell 工具：read_file、list_dir、find_file、search_for_pattern、replace_content、execute_shell_command。在 Claude Code 等已自带同类工具的环境中，这些通常默认关闭。
• 记忆工具：write_memory、read_memory、list_memories、edit_memory、delete_memory。
• 工作流与配置工具：activate_project、onboarding、initial_instructions、get_current_config。

Serena MCP Server 的使用场景

• 按符号浏览大型代码库：“找出 parse_config 的所有调用方，并总结它们各自如何处理错误。”
• 一步完成跨文件重命名，而不是多次搜索替换。
• 重写单个函数：“把 UserService.create 的主体改成先校验邮箱。”
• 在多语言 monorepo 中通过引用查找追踪依赖关系。
• 借助 JetBrains 插件调试：由智能体设置断点、单步执行并查看变量。
• 用 Serena 的记忆在会话之间保存项目笔记，或在新仓库开始时说 "Activate the current dir as project using serena."

Serena MCP Server 与替代方案对比

Serena 专注于语义化、理解符号的代码工作。通用的 Filesystem MCP Server 只能读写文件，而 Context7 或 DeepWiki 这类文档服务器提供的是库文档，并不编辑你的代码。在 Serena 内部，免费的 LSP 后端覆盖导航、符号编辑和重命名；付费的 JetBrains 插件额外提供移动、内联、类型层次结构和调试。

Serena MCP Server 常见问题排查

• 客户端找不到 serena 命令：在 MCP 配置中填写 serena 可执行文件的完整路径。
• 工具已加载但智能体不用：为 Claude Code 或 VS Code 配置 serena-hooks 提醒钩子，或提示 "Activate the current project with Serena and read initial instructions"。
• Claude Code 启动超时：调高 MCP_TIMEOUT，例如设为 60000。
• 语言服务器需要环境变量：Claude Desktop 等图形界面客户端可能不会继承 shell 配置文件中的变量，请在 serena 服务器条目中添加 env 块。
• 全局配置下项目不对：在 Codex、Claude Desktop 或全局 VS Code 配置中，每次会话开始时让智能体把当前目录激活为项目。