Skip to content

Auto-generated English stub on 2026-04-24. Replace with a proper translation.

title: "Serena MCP 配置指南：Claude Code、Codex 和 JetBrains（2026）" description: "Serena MCP 完整配置教程，适用于 Claude Code、Codex CLI 和 JetBrains。支持 30 多种语言，使用 uvx 5 分钟即可完成安装。v1.0 即将发布。" date: 2026-02-13 tags: - Serena - MCP Implementation - Semantic Analysis - AI Coding Environment - 3-steps - server - python - Codex - JetBrains categories: - AI Development & Automation author: Claude Code keywords: - Serena MCP - Serena MCP server - Claude Code Serena - Serena server checklist - Codex MCP - JetBrains MCP

Claude Code 完全ガイド

Serena MCP 配置指南：Claude Code、Codex 和 JetBrains（2026）

2026 年 2 月更新

  • v1.0.0 即将发布（v0.1.4 为最后一个预发布版本）
  • Codex CLI 正式支持 --context codex 选项
  • JetBrains 插件已发布
  • 支持 30 多种语言
  • 破坏性变更：replace_regex 工具已从 ide-assistant/codex 上下文中移除

简介

通过 AI 任务自动化提升您的 Claude 工作流。 Serena MCP 服务器将 Claude Desktop 和 Claude Code 转变为强大的开发助手，具备语义代码分析和智能任务完成功能。本指南展示如何使用 Python uv（而非 npm）进行正确配置，只需 5 分钟即可获得可靠的 AI 驱动开发辅助。适合希望通过自动化文件分析、调试支持和智能代码建议来加速编码生产力的开发者。

您可以实现的目标

  • 完成配置：快速启用 Claude + Serena 集成
  • 实际项目应用：通过索引改善首次响应速度
  • 安全运行：控制 read_only 和 Shell 命令工具

Serena MCP 服务器快速检查清单（2025 年 11 月）

深入了解前的 3 个步骤

  1. 确认 Serena MCP 服务器可通过 uv 启动 — 运行 uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context ide-assistant --project "$(pwd)"，然后打开 http://localhost:24282/dashboard/index.html。
  2. 统一所有客户端配置 — Claude Code 使用 claude mcp add，Claude Desktop 编辑 %APPDATA%/Claude/claude_desktop_config.json（或 macOS 路径），Cursor 在 .cursor/mcp.json 或 Cursor 设置界面中注册 Serena。
  3. 首先锁定 YAML 配置 — 在 ~/.serena/serena_config.yml 和 <project>/.serena/project.yml 中保持 read_only: true，仅在理解风险后才启用额外工具。

在标题和检查清单中直接包含"Serena MCP server"短语，有助于匹配常见搜索意图，同时为新手提供一屏即可完成的成功路径。

1. 快速入门（首先验证连接性）

1.1 添加到 Claude Code（推荐）

# 在项目根目录运行
claude mcp add serena -- \
  uvx --from git+https://github.com/oraios/serena \
  serena start-mcp-server --context ide-assistant --project "$(pwd)"

1.2 可选：通过索引加速首次运行

uvx --from git+https://github.com/oraios/serena serena project index

1.3 健全性检查

  • 仪表板：http://localhost:24282/dashboard/index.html
  • 确认 Claude 可以获取 /mcp__serena__initial_instructions（旧版本中为手动查看）

2. 特定客户端配置

2.1 Claude Code（按项目配置，推荐）

claude mcp add serena -- \
  uvx --from git+https://github.com/oraios/serena \
  serena start-mcp-server --context ide-assistant --project "$(pwd)"

根据需要运行 uvx ... serena project index 以加速首次响应。

2.2 Claude Desktop（编辑本地 JSON）

编辑 claude_desktop_config.json（路径因操作系统而异）：

  • Windows：%APPDATA%\Claude\claude_desktop_config.json
  • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--context", "desktop-app"]
    }
  }
}

保存后完全重启应用程序。日志文件位于同一目录下，文件名为 mcp.log 或 mcp-server-*.log。检查 MCP 图标（锤子）以查看连接状态。

2.3 Cursor（按项目配置）

创建或编辑 .cursor/mcp.json：

{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--context", "ide-assistant"]
    }
  }
}

注意：在 Windows 上，由于已知问题，项目级 mcp.json 可能不会生效。此时请通过 Cursor 设置界面注册，以获得更可靠的效果。

2.4 Codex CLI（OpenAI）

2026 年新增

Serena MCP 现已正式支持 Codex CLI，使用 --context codex 选项。

编辑 ~/.codex/config.toml：

[mcp_servers.serena]
command = "uvx"
args = ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--context", "codex"]

注意：Codex 可能会将 MCP 服务器显示为"failed"状态，但工具实际上仍然正常工作（这是已知的 Codex Bug）。

2.5 JetBrains IDE（Junie / AI Assistant）

2026 年新增

JetBrains 插件已发布 — 利用强大的 IDE 代码分析功能。

在 JetBrains IDE 设置中配置 MCP。JetBrains 集成推荐使用 --context ide。

3. 配置文件（YAML 是正确格式）

Serena 在首次运行时自动生成 YAML 配置文件。

# ~/.serena/serena_config.yml（用户设置）
record_tool_usage_stats: true
included_optional_tools: []

# <project>/.serena/project.yml（项目设置）
read_only: true    # 先设为 true，然后逐步启用所需工具
project_name: my_project

安全提示：execute_shell_command 功能强大但有风险。请从 read_only: true 开始，在理解其作用范围后逐步启用具有写入权限的工具。

4. 仪表板和 SSE

  • 仪表板：http://localhost:24282/dashboard/index.html（默认启用）
  • SSE 连接（仅在需要时使用）：
uv run serena start-mcp-server --transport sse --port 9121

注意：Docker 为实验性支持，在端口和 GUI 方面可能表现不同。生产环境推荐直接使用 uv 调用。

5. 常见陷阱及正确写法

  • 错误：npm install @oraios/serena / node ./node_modules/@oraios/serena/dist/index.js 正确：uvx --from git+https://github.com/oraios/serena serena start-mcp-server

  • 错误：在任意位置放置通用的 mcp-config.json 正确：使用客户端特定的位置（Claude Desktop：claude_desktop_config.json，Cursor：.cursor/mcp.json，Claude Code：claude mcp add ...）

  • 错误：.serenarc.json（JSON） 正确：~/.serena/serena_config.yml 和 <project>/.serena/project.yml（YAML，自动生成）

6. 故障排除（已知问题）

Claude Desktop 无法识别服务器

  1. 完全重启应用程序（从系统托盘退出）
  2. 检查 JSON 语法（逗号、括号）
  3. 使用绝对路径（Windows %APPDATA% 展开问题可通过显式设置 env 变量解决）
  4. 测试手动启动：uvx --from git+https://github.com/oraios/serena serena start-mcp-server
  5. 检查日志：mcp.log / mcp-server-*.log 查看错误详情
  6. MCP Inspector（官方调试工具）用于服务器连接测试

Cursor mcp.json 不生效（Windows）

在 Windows 上，由于已知 Bug，项目级 .cursor/mcp.json 可能不会生效。请通过 Cursor 设置界面（Settings > Features > Model Context Protocol）注册，以获得更可靠的效果。

Serena 工具显示"failed"

部分客户端（如 Codex）存在显示 Bug，工具看似失败但实际执行成功。请通过仪表板或日志查看实际执行结果。

通用调试步骤

  • 从 read_only: true 开始，禁用高风险工具以隔离问题原因
  • 查看 Serena GitHub Issues 了解已知的稳定性/连接性问题

7. CI/运维（务实的边界）

  • MCP 遵循客户端启动服务器的模型。不建议在 CI 中将 Serena 作为直接的 Node 库使用（静态分析请使用 ESLint/flake8/mypy）
  • Serena 适用于交互式辅助和本地工作流加速。CI/CD 静态分析请继续使用现有工具
  • 免费/无需 API 密钥：Serena 本身是免费工具包，但 LLM 使用条款取决于您的客户端（请查看 Claude 等的许可条款）
  • 从 read_only: true 开始，仅逐步启用最少必要的工具

总结

  • 使用基于 uv 的 MCP 服务器作为标准方式；避免 npm/Node 的假设
  • 配置格式为 YAML（~/.serena/serena_config.yml、<project>/.serena/project.yml），自动生成
  • 配置位置因客户端而异：
  • Claude Code：claude mcp add（推荐使用 CLI）
  • Claude Desktop：claude_desktop_config.json（路径因操作系统而异）
  • Cursor：.cursor/mcp.json（Windows 有问题 — 使用界面操作更可靠）
  • 安全第一：read_only: true → 仪表板检查 → 索引 → 逐步启用工具
  • 调试工具：日志（mcp.log 等）、MCP Inspector、GitHub Issues

相关文章

参考文献

  1. 发布于 2025-08-15，Serena v0.1.4 向后移植了 Codex CLI 兼容性修复，扩展了 CLI 功能，并添加了 Swift/Bash 语言服务器，使从标签安装的用户避免 MCP 依赖项损坏问题。 ↩