AgentMatter
EN/中文
提交项目GitHub
MCP 服务器 · 发布者仓库

Serena

Serena 是面向编码 Agent 的开源 MCP 工具，通过语言服务器或可选 JetBrains 后端提供符号检索、引用查找、重命名和结构化代码编辑，并为 Codex CLI 与 App 提供官方配置。

28.6k StarsMITPython今天更新
安装与使用 GitHub
01

项目介绍

Serena 把 IDE 里的语义代码能力带给 Codex 等编码 Agent。与只做文本搜索不同，它通过语言服务器理解符号、定义和引用，让 Agent 可以定位类或函数、追踪调用关系、替换符号体和执行重命名。项目同时提供面向 Codex CLI 与 App 的官方设置命令，适合希望减少大仓库上下文消耗、提高代码导航与修改精度的用户。

02

核心功能

01

语义代码检索

通过语言服务器按符号名称和结构查找定义、子符号与引用，比单纯全文搜索更接近 IDE 导航。

02

符号级编辑与重命名

可以替换函数或类的主体、在符号前后插入代码，并使用语言智能执行重命名。

03

多语言项目分析

默认 LSP 后端支持 40 多种语言，并能在多语言项目中并行管理多个语言服务器。

04

项目记忆与配置

可保存项目相关记忆，并通过上下文、模式、全局配置和项目配置调整工具集与行为。

05

多种 MCP 连接方式

常用方式是让客户端通过 STDIO 启动 Serena，也可以自行启动 Streamable HTTP 服务后连接端点。

Serena 架构图展示用户、AI 客户端、MCP Server 工具与语言智能后端之间的调用关系
AI 客户端通过 MCP 调用 Serena 的符号查找、引用查询、代码替换和重命名工具，再由语言服务器或 JetBrains 后端提供语义能力。查看仓库原图
03

安装与连接

先安装 uv，再安装并初始化 Serena；随后使用官方 Codex 设置命令写入 MCP 配置。首次连接时只对受信任且已纳入版本控制的项目操作，并先验证只读符号查询。

AI AGENT INSTALL

让 AI Agent 帮你安装

把这段话发送给 Codex、Claude Code 或其他可以操作本地环境的 AI Agent。

请帮我安装并连接 Serena MCP。项目地址：https://github.com/oraios/serena。先阅读 README.md、docs/02-usage/010_installation.md、docs/02-usage/030_clients.md、docs/02-usage/070_security.md、LICENSE 和最新 release。确认已安装 uv，然后运行 `uv tool install -p 3.13 serena-agent` 与 `serena init`，再运行 `serena setup codex`。不要把 Streamable HTTP 服务暴露到非本机网络，不要修改我现有的其他 Codex MCP 配置。遇到下载额外语言服务器、执行 shell 命令、修改项目文件、扩大目录访问、覆盖配置或申请额外权限时先说明并征得同意。安装后用 `/mcp` 检查连接，激活当前项目，并只做一次无副作用的符号查找和引用查询验证。
01开始前准备
  • uv 已安装并加入 PATH
  • Codex CLI 或 Codex App 已可使用 MCP
  • 准备操作的代码仓库可信且最好已纳入 Git 版本控制
02复制安装命令或配置
uv tool install -p 3.13 serena-agent
serena init
03按步骤完成安装
  1. 1
    安装并初始化 Serena

    安装 uv 后运行 `uv tool install -p 3.13 serena-agent`，再运行 `serena init` 验证 CLI 并初始化默认语言服务器后端。

  2. 2
    写入 Codex MCP 配置

    运行 `serena setup codex`；也可以按官方文档把 Serena 的 command、args 和 15 秒启动超时手动写入 `~/.codex/config.toml`。

  3. 3
    连接并激活项目

    在 Codex 中运行 `/mcp` 检查连接。Codex App 用户先要求 Serena 激活当前目录，再读取项目初始说明。

  4. 4
    执行最小只读验证

    让 Codex 使用 Serena 查找一个已知符号并列出引用；确认准确后，再按需启用替换符号体或重命名等写操作。

如何确认安装成功

运行 `serena setup codex` 后重启或重新连接 Codex，执行 `/mcp` 确认 Serena 已连接；在 Codex App 中先提示“Activate the current dir as project using serena”，然后让它查找一个已知符号和该符号的引用，核对结果是否与项目一致。

使用前注意
  • Codex App 中通常需要显式激活当前目录
  • 可设置 SERENA_USAGE_REPORTING=false 关闭启动使用统计
  • 安全敏感环境应在容器或其他沙箱中运行
04

使用场景

SCENARIO 01

大型代码库导航

用符号和引用查询快速定位相关实现，减少向模型发送整文件或大量搜索结果。

SCENARIO 02

跨文件安全重构

先查看符号和调用关系，再执行符号体替换或重命名，并配合 Git diff 与测试审查结果。

SCENARIO 03

长期项目上下文

把架构、约定和常用操作保存为项目记忆，供后续 Agent 会话复用。

05

使用评价

Serena 的优势不是再提供一套文本搜索，而是把语言服务器的符号级理解以 MCP 工具交给编码 Agent。官方 Codex 配置、40 多种语言和活跃维护让它很适合复杂仓库。代价是本地权限面较大，语言服务器可能下载依赖，HTTP 模式也需要额外保护，因此应把可信仓库、版本控制、最小工具集和沙箱作为实际使用前提。本评价基于一手文档和仓库检查，未实际安装运行。

值得一试的地方

  • 为 Codex CLI 与 App 提供官方配置
  • 符号检索、引用和结构化编辑比纯文本工具更适合大型仓库
  • MIT 开源后端覆盖 40 多种语言且近期持续维护

使用前要知道

  • 读取、修改文件和命令执行能力带来较高本地权限风险
  • 部分语言需要额外环境或语言服务器依赖
  • 本次未完成安装与功能实测
06

README

Serena

Overview

Serena 是面向编码 Agent 的开源 MCP 工具，通过语言服务器或可选 JetBrains 后端提供符号检索、引用查找、重命名和结构化代码编辑，并为 Codex CLI 与 App 提供官方配置。 A powerful coding agent toolkit providing semantic retrieval and editing capabilities (MCP server & other integrations)

Getting started

  • 先安装 uv，再安装并初始化 Serena；随后使用官方 Codex 设置命令写入 MCP 配置。首次连接时只对受信任且已纳入版本控制的项目操作，并先验证只读符号查询。
  • Serena 是编码 Agent 工具包，本身不包含负责完成任务的 LLM，而是通过 MCP 向 Codex、Claude Code、VS Code、Cursor、JetBrains 等客户端提供工具。
  • 默认免费开源后端使用 LSP，并覆盖 40 多种编程语言；可选 Serena JetBrains Plugin 为付费后端，提供免费试用。
  • 运行 `serena setup codex` 后重启或重新连接 Codex，执行 `/mcp` 确认 Serena 已连接；在 Codex App 中先提示“Activate the current dir as project using serena”，然后让它查找一个已知符号和该符号的引用，核对结果是否与项目一致。

Configuration

uv tool install -p 3.13 serena-agent
serena init
在 GitHub 阅读完整 README →