🔥 Serena：24k Stars 的 AI 编程 MCP 工具箱，给你的 Coding Agent 装上 IDE 大脑

老实说，用 Claude Code / Codex 写代码最烦什么？不是它写不出来，是它经常在一个文件里转来转去找不到关键函数。跨文件重命名个变量，它能花 8-12 步才能搞定，还得小心翼翼地确认不会改错地方。

Serena 这玩意儿就是来解决这个问题的。 它是给 Coding Agent 用的 MCP 工具集，24k Stars，相当于给你的 AI Agent 装了个 IDE 的大脑——能理解符号、找引用、做重构，跟老程序员用 JetBrains 一样自然。

🧠 它怎么工作的

Serena 走的是 MCP（Model Context Protocol）协议，不绑定任何特定厂商。你的 Claude Code、Codex、OpenCode、Gemini CLI，甚至 VSCode 和 JetBrains 里的 Copilot，都能接上它。

最骚的是，它不是在文本层面做替换——它在符号层面理解代码。比如你要把 getUserData 改名为 fetchUserProfile，Serena 不是傻傻地全局搜索替换，而是找到这个符号的定义和所有引用，语义准确地改名。

两个后端可选：

Language Server（免费开源）：基于 LSP，支持 40+ 编程语言，默认方式

JetBrains Plugin（付费，有试用）：用 IntelliJ 级别的代码分析引擎，能做更深的依赖跟踪和调试

⚡ 真实效果

官方做了个盲测，让 Agent 自己评价 Serena 的价值。注意——是 Agent 自己说的，不是人吹的：

Opus 4.6 in Claude Code："Serena 的语义工具是我工具箱里最 impactful 的补充——跨文件重命名、移动、引用查找，原来要 8-12 步的谨慎操作，现在一次调用搞定。"

GPT 5.4 in Codex："它把脆弱的文本手术变成了冷静、自信的代码变更。"

🛠 快速上手

安装前提： 先装 uv

# 安装 Serena
uv tool install -p 3.13 serena-agent@latest --prerelease=allow

# 初始化
serena init

# 连接到 Claude Code（一键配置）
serena setup claude-code

连到 Codex 的话：

# 全局配置（用户级）
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)"

JetBrains 用户： 在 Copilot 设置里的 MCP 配置加上：

{
    "servers": {
      "serena": {
        "type": "stdio",
        "command": "serena",
        "args": ["start-mcp-server", "--context=jb-copilot-plugin"]
      }
    }
}

🔧 核心能力一览

符号查找：找定义、找引用、看类型层级，不用一行行翻文件

语义重构：重命名符号、移动文件/目录、内联变量——比全局替换安全 N 倍

符号编辑：替换函数体、在符号前后插入代码、安全删除，比正则替换 token 效率高太多

交互调试（JetBrains 版独有）：设断点、看变量、控制执行流，Agent 自 debug 不再是梦

记忆系统：跨 session 共享知识，长期项目不用反复从头学

⚠️ 避坑

读到这你可能想装了，但有几点要注意：

别从 MCP 市场装 — 官方说里面都是过时的命令，直接走 uv tool install

2. Claude Code 的新版偏内置工具 — 官方推荐启动时加 --system-prompt="$(serena prompts print-cc-system-prompt-override)" 来纠正 bias

3. 命令找不到？ — 客户端可能不继承 shell PATH，用完整路径或设 env 字段

4. Serena 工具不被使用？ — 设 hooks（.claude/settings.json 里的 PreToolUse hooks）强制 Agent 在关键时刻加载

📌 要点总结

Serena 是 MCP 协议的工具集，给 Coding Agent 装上了 IDE 级别的代码理解能力

支持 40+ 编程语言，通过 LSP 或 JetBrains Plugin 两种后端

一个 uv command 装好，一键 serena setup claude-code 连上

Agent 自评证实：跨文件重构耗时从 8-12 步缩到 1 步

免费开源，MIT 协议，不绑定厂商，连谁用谁

🔥 Serena: 24k Stars MCP Toolkit — Give Your Coding Agent an IDE-Grade Brain

Repo: https://github.com/oraios/serena | ⭐ 24,170 Stars | 🛠 Python | Author: oraios

Let's be real — the most annoying thing about Claude Code / Codex isn't that it can't write code. It's that it fumbles around files looking for the right function. A cross-file rename takes 8–12 painstaking steps, and you're constantly anxious it'll break something.

Serena fixes this. It's an MCP toolkit for coding agents — 24k stars — that gives your AI agent an IDE-grade brain. It understands symbols, finds references, and refactors code the way a seasoned dev navigates JetBrains.

🧠 How It Works

Serena speaks MCP (Model Context Protocol) — vendor-agnostic. Your Claude Code, Codex, OpenCode, Gemini CLI, or even Copilot in VSCode/JetBrains can all plug into it.

The kicker: it operates at the symbol level, not the text level. Renaming getUserData to fetchUserProfile? Serena finds the symbol definition and all its references, and renames semantically. No blind global search-replace.

Two backends:

Language Server (free, open-source): LSP-based, 40+ languages, default

JetBrains Plugin (paid, free trial): IntelliJ-grade code analysis for deep dependency tracking and debugging

⚡ Real Results

The team ran a blind eval — asking the agents themselves to rate Serena. Yes, the AI agents said this:

Opus 4.6 in Claude Code: "Serena's semantic tools are the single most impactful addition to my toolkit — cross-file renames, moves, and reference lookups that cost 8–12 careful steps collapse into one atomic call."

GPT 5.4 in Codex: "It turns fragile text surgery into calmer, faster, more confident code changes."

🛠 Quick Start

Prerequisite: Install uv

# Install Serena
uv tool install -p 3.13 serena-agent@latest --prerelease=allow

# Initialize
serena init

# Connect to Claude Code (one-shot setup)
serena setup claude-code

For Codex users:

# Global (user-level)
claude mcp add --scope user serena -- serena start-mcp-server --context claude-code --project-from-cwd

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

JetBrains users: Add to Copilot's MCP config:

{
    "servers": {
      "serena": {
        "type": "stdio",
        "command": "serena",
        "args": ["start-mcp-server", "--context=jb-copilot-plugin"]
      }
    }
}

🔧 Core Capabilities

Symbol lookup: find definitions, references, type hierarchies — no more skimming files manually

Semantic refactoring: rename symbols, move files/dirs, inline variables — way safer than global search-replace

Symbolic editing: replace function bodies, insert before/after symbols, safe delete — far more token-efficient than regex

Interactive debugging (JetBrains only): set breakpoints, inspect variables, control execution flow — agents debugging themselves

Memory system: share knowledge across sessions, so long-term projects don't relearn everything from scratch

⚠️ Gotchas

Don't install from MCP marketplaces — stale commands. Use uv tool install

2. Claude Code bias: newer CC versions favor built-in tools. Override with --system-prompt="$(serena prompts print-cc-system-prompt-override)"

3. Command not found? Client may not inherit shell PATH — use full path or set env

4. Tools not invoked? Set up PreToolUse hooks in .claude/settings.json

📌 Key Takeaways

Serena = MCP toolkit giving coding agents IDE-grade code understanding

40+ languages supported via LSP or JetBrains Plugin backends

One uv tool install + one serena setup and you're done

Agents self-report: cross-file refactors go from 8–12 steps → 1 call

Free, open-source (MIT), vendor-agnostic