Serena MCP Server:安装与配置指南 (2026)
通过 MCP 为 Serena 设置具备代码感知能力的 AI 交互
开始使用 Hypereal 构建
通过单个 API 访问 Kling、Flux、Sora、Veo 等。免费积分开始,扩展到数百万。
无需信用卡 • 10万+ 开发者 • 企业级服务
Serena MCP Server:安装与配置指南 (2026)
Serena 是一款开源的 MCP (Model Context Protocol) 服务端,它能让 AI 助手对你的项目进行深度且具备代码意识的访问。与简单的文件读取工具不同,Serena 集成了 Language Server Protocol (LSP),为你的代码库提供语义化理解——包括符号查询、跳转到定义、查找引用以及智能代码导航。
本指南涵盖了 Serena 的安装、针对项目的配置,以及将其连接到 Claude Desktop、Cursor 和 Claude Code 等兼容 MCP 的客户端。
什么是 Serena?
Serena 基于 Anthropic 创建的 MCP 标准构建。它充当了 AI 模型与代码库之间的桥梁,提供:
- 语义化代码分析:通过 LSP 实现(不仅是文本搜索)
- 符号解析:查找定义、引用和实现
- 项目感知上下文:理解项目结构和依赖关系
- 文件操作:在完整的上下文支持下读取、写入和修改文件
- Git 集成:查看 diff、暂存更改并理解版本历史
| 功能 | Serena | 基础文件 MCP | IDE 插件 |
|---|---|---|---|
| 文件读写 | 是 | 是 | 是 |
| 语义化代码导航 | 是 | 否 | 是 |
| 符号查询 | 是 | 否 | 是 |
| 跨文件引用 | 是 | 否 | 是 |
| 支持任意 MCP 客户端 | 是 | 是 | 否 |
| 语言支持 | 通过 LSP 服务端 | 不适用 | 单一 IDE |
| 开源 | 是 | 视情况而定 | 视情况而定 |
前置条件
在安装 Serena 之前,请确保你已具备:
- 已安装 Python 3.10+
- uv (Python 包管理器) 或 pip
- 对应语言支持的 LSP 服务端 (参见下文的语言设置)
- 兼容 MCP 的客户端 (Claude Desktop, Cursor, Claude Code 等)
安装
方法 1:使用 uv 安装 (推荐)
# 如果没有 uv,请先安装
curl -LsSf https://astral.sh/uv/install.sh | sh
# 克隆 Serena 仓库
git clone https://github.com/oramasearch/serena.git
cd serena
# 创建虚拟环境并安装依赖
uv sync
方法 2:使用 pip 安装
git clone https://github.com/oramasearch/serena.git
cd serena
python -m venv .venv
source .venv/bin/activate # Windows 用户: .venv\Scripts\activate
pip install -e .
方法 3:通过 uvx 安装 (无需克隆)
# 直接运行而无需克隆仓库
uvx --from git+https://github.com/oramasearch/serena.git serena
项目配置
Serena 需要一个项目配置文件来获知你的代码库信息以及应使用哪个 LSP 服务端。
创建项目配置文件
在你的项目根目录下创建一个 .serena/config.yaml 文件:
# .serena/config.yaml
project_name: "my-project"
description: "你的项目简述"
# Language server 配置
lsp:
language: "typescript"
command: "typescript-language-server"
args: ["--stdio"]
root_path: "."
# 包含的文件模式
include:
- "src/**/*.ts"
- "src/**/*.tsx"
- "lib/**/*.ts"
- "*.json"
# 排除的文件模式
exclude:
- "node_modules/**"
- "dist/**"
- "build/**"
- ".git/**"
- "*.lock"
特定语言的 LSP 配置
TypeScript / JavaScript
# 安装 LSP 服务端
npm install -g typescript-language-server typescript
lsp:
language: "typescript"
command: "typescript-language-server"
args: ["--stdio"]
Python
# 安装 pyright
npm install -g pyright
# 或者安装 python-lsp-server
pip install python-lsp-server
# 使用 Pyright
lsp:
language: "python"
command: "pyright-langserver"
args: ["--stdio"]
# 或使用 pylsp
lsp:
language: "python"
command: "pylsp"
Rust
# 安装 rust-analyzer (通常包含在 rustup 中)
rustup component add rust-analyzer
lsp:
language: "rust"
command: "rust-analyzer"
Go
go install golang.org/x/tools/gopls@latest
lsp:
language: "go"
command: "gopls"
Java
lsp:
language: "java"
command: "jdtls"
连接至 MCP 客户端
Claude Desktop
将 Serena 添加到你的 Claude Desktop MCP 配置文件中。
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"serena": {
"command": "uv",
"args": [
"run",
"--directory", "/path/to/serena",
"serena",
"--project-dir", "/path/to/your/project"
]
}
}
}
修改配置后请重启 Claude Desktop。
Claude Code
将 Serena 添加到你的 Claude Code MCP 设置:
claude mcp add serena -- uv run --directory /path/to/serena serena --project-dir /path/to/your/project
或者将其添加到 .claude/settings.json:
{
"mcpServers": {
"serena": {
"command": "uv",
"args": [
"run",
"--directory", "/path/to/serena",
"serena",
"--project-dir", "/path/to/your/project"
]
}
}
}
Cursor
在 Cursor 中,进入 Settings > MCP Servers 并添加:
{
"serena": {
"command": "uv",
"args": [
"run",
"--directory", "/path/to/serena",
"serena",
"--project-dir", "/path/to/your/project"
]
}
}
可用的 MCP 工具
连接成功后,Serena 会向你的 AI 客户端开放以下工具:
| 工具 | 描述 |
|---|---|
read_file |
读取带行号的文件内容 |
write_file |
写入或创建文件 |
list_directory |
列出文件和目录 |
search_text |
在文件中搜索文本模式 |
find_symbol |
查找符号定义(函数、类、变量) |
get_references |
查找符号的所有引用 |
get_definition |
跳转至符号定义 |
get_hover_info |
获取符号的类型信息和文档 |
get_diagnostics |
获取 LSP 诊断信息(错误、警告) |
git_diff |
查看 git diff |
git_log |
查看 git 历史 |
git_stage |
暂存待提交文件 |
使用示例
连接 Serena 后,你可以向 AI 助手提问,例如:
- “查找整个项目中
UserService类的所有引用” - “
processPayment函数的类型签名是什么?” - “显示项目中所有的诊断信息(错误和警告)”
- “跳转到
handleAuth的定义并解释它的作用” - “重构
calculateTotal函数以处理边缘情况”
AI 将使用 Serena 的语义化工具智能地导航你的代码库,而不是进行肤浅的文本搜索。
故障排除
LSP 服务端未启动
# 验证 LSP 服务端是否已安装且可访问
which typescript-language-server # 应该返回路径
typescript-language-server --stdio # 应该无错启动 (Ctrl+C 退出)
与 Claude Desktop 的连接问题
- 检查配置文件是否为有效的 JSON(无末尾逗号)
- 验证路径是绝对路径,而非相对路径
- 检查 Claude Desktop 日志:Help > Show Logs
- 任何配置更改后请求重启 Claude Desktop
Serena 找不到符号
- 确保 LSP 服务端支持你的语言特性
- 检查项目的
include模式是否匹配你的源文件 - 验证
root_path指向了正确的项目目录 - 某些 LSP 服务端需要先进行构建步骤(例如 TypeScript 的
tsc --build)
性能问题
对于大型项目,请优化你的配置:
# 排除大型目录
exclude:
- "node_modules/**"
- "dist/**"
- ".git/**"
- "coverage/**"
- "*.min.js"
- "vendor/**"
# 仅限于源文件
include:
- "src/**/*.ts"
- "src/**/*.tsx"
Serena 与其他 MCP 服务端的对比
| 功能 | Serena | filesystem MCP | GitHub MCP |
|---|---|---|---|
| 文件操作 | 是 | 是 | 有限 |
| LSP 集成 | 是 | 否 | 否 |
| 符号导航 | 是 | 否 | 否 |
| Git 集成 | 是 | 否 | 是 |
| 远程仓库 | 否 | 否 | 是 |
| 设置复杂度 | 中 | 低 | 低 |
| 最佳用途 | 深度代码分析 | 简单文件访问 | GitHub 工作流 |
总结
Serena 通过集成 LSP 提供语义化理解,彻底改变了 AI 助手与代码交互的方式。AI 不再将你的代码库视为扁平的文本文件,而是可以导航定义、查找引用并理解类型——这使得它在处理复杂的重构、调试和代码审查时效率大幅提升。
如果你正在构建需要多媒体生成(如图像、视频和虚拟人)的 AI 应用,欢迎免费试用 Hypereal AI —— 包含 35 个积分,无需信用卡。它能与任何接入 MCP 的开发工作流完美配合。
