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 的开发工作流完美配合。