接入客户端：Claude Code 与 Cursor ide context

你将得到什么

• Claude Code 侧：用 serena setup claude-code 或官方 claude mcp add … 完成接入，并用 /mcp 验证
• Cursor（及同类 IDE 助手）侧：按官方推荐的 --context ide 写好 MCP 启动项
• 一次「激活项目 + 让 Agent 用符号工具」的跟做话术，避免只停在配置文件

开始前准备

1. 已完成第 1 课：serena 在 PATH 上，serena init 已成功。
2. 至少一个客户端：Claude Code 或 Cursor（本课两条路径都写；你可只做其一）。
3. 从真实项目目录启动客户端。官方警告：带 --project-from-cwd 时若从家目录启动，可能扫描整棵 home 导致超时。

通用规则（先读 30 秒）

官方总原则：向 MCP 客户端登记 Serena 时，二选一——

1. stdio：给客户端一条能拉起 MCP 的命令（最常见）
2. HTTP/SSE：你先自己起 Serena HTTP 模式，再把 URL 填给客户端

本课只跟做 stdio + 官方示例命令。

另有两点影响「工具会不会被用起来」：

• 工作区 vs 全局配置：VS Code / Claude Code 偏每工作区；Codex / Claude Desktop 偏全局。全局配置时常需让 Agent 激活当前项目（例如提示语 Activate the current dir as project using serena）。
• context：启动参数里的 --context … 会裁剪工具集，减少与客户端内置工具重复。Claude Code 用 claude-code；Cursor 等用官方推荐的 ide。

路径 A：Claude Code（官方一键优先）

A1. 一键 setup（推荐先试）

官方 Clients 页：

serena setup claude-code

对照结果：命令结束且无报错。然后在 Claude Code 里执行：

/mcp

对照结果：列表中可见 serena，状态为已连接 / 可重连。若启动偏慢，官方建议提高超时，例如在 shell profile 中：

export MCP_TIMEOUT=60000

A2. 手动：用户级（所有项目）

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

A3. 手动：仅当前项目

在项目根目录执行：

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

A4. 官方强烈建议：缓解「Agent 不用 Serena」

近期 Claude Code / Opus 对内置工具描述极长，可能几乎不调用外部 MCP。官方给出启动覆盖：

claude --system-prompt="$(serena prompts print-cc-system-prompt-override)"

也可把该 prompt 内容写入 CLAUDE.md，但官方称对强偏置可能仍不够。

进一步可选：在 .claude/settings.json（项目）或 ~/.claude/settings.json（全局）配置官方 hooks（serena-hooks remind / activate / cleanup / auto-approve）。完整 JSON 见 Clients · Claude Code · Hooks；hooks 标为 alpha，按需启用。

路径 B：Cursor（及 Cline / Windsurf 等）

官方把 Cursor 归在 MCP-Enabled IDEs，并写明：一般推荐 --context ide，以减少与 IDE 内置检索/编辑工具重复。

B1. 编辑 MCP 配置

Cursor 通常使用用户级或项目级 mcp.json（路径以你本机 Cursor 版本为准，常见为 ~/.cursor/mcp.json 或项目 .cursor/mcp.json）。新增类似条目（把项目路径换成你的绝对路径）：

{
  "mcpServers": {
    "serena": {
      "command": "serena",
      "args": [
        "start-mcp-server",
        "--context",
        "ide",
        "--project",
        "/ABS/PATH/TO/YOUR/REPO"
      ]
    }
  }
}

若希望随「当前工作目录」切换项目，可按官方其它客户端的写法改用 --project-from-cwd（仍建议从仓库目录打开 Cursor，勿在 $HOME 乱启）：

{
  "mcpServers": {
    "serena": {
      "command": "serena",
      "args": [
        "start-mcp-server",
        "--context",
        "ide",
        "--project-from-cwd"
      ]
    }
  }
}

对照结果：保存配置后重启 Cursor（或按 UI 重载 MCP）。在 Agent / MCP 工具面板应能看到 Serena 相关工具。

若提示找不到 serena：把 "command" 改成第 1 课里 which serena 得到的绝对路径（官方 Common Pitfalls）。

B2. 激活项目（全局或未绑死项目时）

若 Serena 未自动激活当前仓库，在对话里明确说（官方示例语气）：

Activate the current dir as project using serena and read initial instructions

对照结果：Agent 应调用 Serena 的项目激活类工具，并开始按 Serena 说明使用符号工具。

步骤：首轮验证（两条路径共用）

在已连接的客户端里，打开一个你熟悉的仓库，试一次符号级请求（示例，按你的语言改类名）：

用 Serena 查找符号 FooBar 的定义，并列出主要引用位置；不要只用全文 grep。

对照结果（成功时大致应满足）：

• 工具调用列表里出现 Serena 的符号/引用类工具（名称随 context 略有差异）
• 返回的是结构化符号结果，而不是大段无关文件全文

再试一句重构向（先在小分支 / 可回滚仓库）：

用 Serena 在符号级别解释如何重命名 FooBar，先只分析引用、不要直接改文件。

对照结果：Agent 能基于引用图说明影响面；你确认后再允许实际编辑。

其它客户端（选读）

同一 Clients 页还给出 Codex（serena setup codex）、Claude Desktop（desktop-app context）、VS Code、Grok、JetBrains Junie 等示例。原则相同：选对 context + 项目目录。需要时直接打开官方页复制对应 JSON。

本课检查清单

• Claude Code：/mcp 可见 serena，或 Cursor：MCP 面板可见 Serena 工具
• 已在真实项目目录工作（非盲目扫 $HOME）
• 完成至少一次「符号查找 / 引用」对话，确认 Agent 调用了 Serena
• （Claude Code）知悉官方 system-prompt override / hooks 可选项

延伸阅读（官方）

• Tools overview
• Workflow
• Configuration