1. Claude Code 接入 Serena 时 MCP endpoint 到底该填什么Claude Code 本身已经能读文件、跑命令、改代码但它在“找代码”这件事上一直有个隐性成本每次都要靠 grep、glob、read 去遍历目录遇到大项目时 token 消耗和等待时间都会明显上升。Serena 这个代码辅助分析器解决的就是这个问题它通过 LSP 提供符号级检索让 Claude Code 能直接定位函数、类、变量的定义和引用而不是把整个文件读进来再判断。适合谁用适合本地开发环境里项目文件超过几百个、经常需要跨文件改逻辑、又不想每次对话都重新喂上下文的开发者。我试过在同一个仓库里对比不接 Serena 时让 Claude Code 找某个 service 层函数的调用链它要读五六个文件才能拼出关系接上 Serena 后一次find_symbol加一次find_referencing_symbols就能拿到结构化结果。差别不在模型智商而在“检索方式”从字符匹配升级成了语义符号匹配。这里的关键环节是 MCP endpoint 配置。Claude Code 通过 MCP 协议连接 Serena 的 serverendpoint 写错、路径写错、或者--project参数没给对都会导致工具列表里看不到 Serena或者调用时报local proxy failed。本文就围绕这个配置环节给出可复制的 MCP endpoint 片段、settings 修改步骤以及一次 Serena 工具调用的连通性验证。目标很明确配置完成后你能稳定调用代码分析能力而不是每次重启终端都要重新排查。需要先说明一点Serena 是本地运行的 MCP server不是云端服务。所以 endpoint 的本质是“Claude Code 用什么命令把 Serena 拉起来”。TaoToken 在这里的角色是提供 Claude Code 可用的模型接入层让 Claude Code 的请求走统一入口而 Serena 仍然跑在你本机。两者不冲突一个是模型侧一个是工具侧。2. TaoToken 前置准备与 Claude Code 模型接入在配 Serena 之前先把 Claude Code 的模型接入理顺。因为如果模型侧本身就不通Serena 配好了也验证不了。TaoToken 的 API 地址是https://taotoken.net/api官网是https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。你需要先在控制台创建一个 API Key然后把它写进 Claude Code 的环境变量或 settings 文件。Claude Code 读取配置的优先级大致是环境变量 项目级 settings 用户级 settings。本地开发建议用项目级.claude/settings.json这样不同仓库可以带不同配置也不会污染全局。下面是一个最小可用的 settings 片段路径是项目根目录下的.claude/settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoTokenKey, ANTHROPIC_MODEL: claude-sonnet-4-5-20250929 } }这里三个字段缺一不可。ANTHROPIC_BASE_URL指向 TaoToken 的 API 入口ANTHROPIC_AUTH_TOKEN放你创建的 KeyANTHROPIC_MODEL指定要调用的模型 ID。模型 ID 要以控制台实际提供的为准不要凭记忆写。写完后可以用claude启动一次随便问一句“当前目录有哪些文件”能正常返回就说明模型侧通了。如果你更习惯用环境变量也可以在 shell 里 exportexport ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的TaoTokenKey export ANTHROPIC_MODELclaude-sonnet-4-5-20250929注意环境变量方式在每次新开终端都要重新设置适合临时调试长期使用还是写进 settings 文件更稳。另外如果你同时装了多个 MCP server建议在 settings 里把 MCP 相关配置也集中管理避免散落在不同地方导致排查困难。TaoToken 的 Key 创建入口在控制台的 API Keys 页面文档在接入文档里模型对话可以在模型对话页面直接试。这三个入口分别对应不同阶段创建 Key、查接入方式、验证模型是否可用。建议按这个顺序走一遍再进入 Serena 配置。还有一个容易忽略的点Claude Code 的版本。旧版本对 MCP 的支持不完整建议用较新的版本。可以用claude --version确认如果版本太旧先升级再配 Serena否则会出现“配置写了但工具不出现”的情况。3. Serena MCP endpoint 可复制配置与 settings 修改Serena 的 MCP endpoint 配置有两种主流写法一种是用uvx直接从 Git 仓库拉取并运行另一种是先 clone 到本地再用uv run启动。前者省事后者可控。本地开发环境我推荐第二种因为 clone 下来后可以锁定版本、看源码、排查问题。先看uvx写法适合快速验证claude mcp add serena -- uvx --from githttps://github.com/oraios/serena serena-mcp-server --project $(pwd)这条命令的意思是让 Claude Code 注册一个叫serena的 MCP server启动方式是uvx从指定 Git 仓库拉取 serena然后运行serena-mcp-server并把当前目录作为项目上下文。$(pwd)在 macOS/Linux 下取当前路径Windows 下要换成具体路径比如--project D:\code\myproject。如果你要写进 settings 文件而不是用命令行注册可以这样写。路径是项目根目录.claude/settings.json{ mcpServers: { serena: { command: uvx, args: [ --from, githttps://github.com/oraios/serena, serena-mcp-server, --project, /Users/yourname/code/myproject ] } } }注意--project后面必须是绝对路径不能用$(pwd)因为 settings 文件不会经过 shell 展开。这是很多人配置后工具不生效的第一个坑。再看 clone 写法适合长期使用git clone https://github.com/oraios/serena /Users/yourname/mcp-servers/serena claude mcp add serena -- uv run --directory /Users/yourname/mcp-servers/serena serena-mcp-server --project /Users/yourname/code/myproject对应的 settings 片段{ mcpServers: { serena: { command: uv, args: [ run, --directory, /Users/yourname/mcp-servers/serena, serena-mcp-server, --project, /Users/yourname/code/myproject ] } } }这里三件套要写全Base URL 是 TaoToken 的https://taotoken.net/apiKey 是你的sk-开头令牌Model ID 是控制台里实际可用的模型名。Serena 本身不碰这三个它只负责工具侧但 Claude Code 要同时读模型配置和 MCP 配置所以两份配置都要在。还有一个参数--context ide-assistant如果你只用 Claude Code可以不加这个参数是给 Cursor 这类 IDE 增强用的。加了也不会报错但没必要。配置写完后重启终端再启动claude。用/mcp命令查看已注册的 MCP server如果看到serena且状态是 connected说明 endpoint 配置生效了。如果显示 failed先看下一节的排查。4. 验证 Serena 工具调用与连通性配置生效后不要急着让它改代码先做一次最小连通性验证。启动 Claude Code输入/mcp确认 serena 在列表里然后新开一个对话执行 Serena 的初始化指令。注意这个指令不是直接手敲的建议做成自定义快捷方式。它的作用是让 Claude Code 加载 Serena 的符号工具说明和项目记忆。初始化完成后让 Claude Code 调用一次符号检索。比如你有一个 Python 项目里面有services/user_service.py你可以直接说用 serena 的 get_symbols_overview 看一下 services/user_service.py 的顶层符号如果连通正常Claude Code 会返回类似这样的结构化结果File: services/user_service.py Symbols: - class UserService - method __init__ - method get_user - method create_user - method update_user这说明 Serena 已经通过 LSP 解析了文件并把符号树返回给了 Claude Code。接下来再验证一次引用查找用 find_referencing_symbols 找 UserService.get_user 被哪些地方引用了正常返回会列出引用位置和代码片段。到这一步说明 MCP endpoint 配置、Serena server 启动、LSP 解析、工具调用链路全部通了。如果第一次调用返回的是空结果先确认--project指向的目录里确实有对应文件且文件扩展名是 Serena 支持的。Serena 对 Python 支持最好对纯 JS 的 Express 项目也不错但对.vue单文件组件的语义解析支持有限这是已知限制不是配置问题。验证通过后你可以把常用指令做成快捷方式比如在项目里放一个.claude/commands/serena-init.md内容就是初始化提示词。这样每次新对话只要敲一个短命令就能加载 Serena 上下文不用重复输入长指令。5. 常见报错排查401、local proxy failed、reading choices、OAuth配置过程中最容易遇到四类报错逐个说。第一类401 Unauthorized。这个基本是 TaoToken 的 Key 问题。检查.claude/settings.json里的ANTHROPIC_AUTH_TOKEN是否以sk-开头、有没有多余空格、有没有过期。如果 Key 是对的再看ANTHROPIC_BASE_URL是不是写成了https://taotoken.net/api末尾不要多加斜杠。改完重启终端再试。第二类local proxy failed。这个通常出现在 MCP server 启动阶段说明 Claude Code 尝试拉起 Serena 但失败了。常见原因有三个uv或uvx没装、--project路径不存在、或者 Python 环境找不到。先在终端手动跑一遍启动命令看报什么错。比如手动执行uvx --from githttps://github.com/oraios/serena serena-mcp-server --project /Users/yourname/code/myproject如果提示uvx: command not found说明 uv 没装需要先装 uv。如果提示找不到 Python建议预装 miniconda让 uv 能定位到 Python 解释器。手动能跑通Claude Code 里基本也能通。第三类reading choices相关报错。这个多出现在模型返回流解析阶段通常是模型 ID 写错或 TaoToken 侧模型不可用。检查ANTHROPIC_MODEL是否和控制台里可用的模型 ID 完全一致大小写、日期后缀都不能差。如果模型 ID 对但还报换一个可用模型试排除是单个模型的问题。第四类OAuth相关报错。Claude Code 某些版本会尝试走 OAuth 流程如果你用的是 API Key 接入需要在 settings 里明确用ANTHROPIC_AUTH_TOKEN不要同时留 OAuth 相关字段。把冲突字段删掉只保留 Base URL、Key、Model ID 三件套。排查顺序建议先手动跑 Serena 启动命令确认工具侧能起来再用claude发一句普通对话确认模型侧能通最后用/mcp看 server 状态。三层都通再验证工具调用。这样出问题时能快速定位是哪一层。6. 稳定调用代码分析能力的后续配置建议Serena 配好之后有几个习惯能让它更稳。第一每个项目单独配--project不要用一个 Serena 实例跨多个仓库否则符号索引会混。第二新开对话先跑初始化指令让 Claude Code 加载项目记忆和工具说明否则它可能不知道有哪些符号工具可用。第三定期更新 Serena 仓库LSP 支持的语言和解析能力在持续迭代。如果你长期用 Claude Code 做编码和 Agent 任务可以考虑 Coding Plan把模型调用和工具链统一管理。验证模型是否可用用模型对话创建和管理 Key 用 API Keys接入细节查接入文档。这几个入口按需组合基本能覆盖从配置到排障的全流程。最后提醒一句Serena 是增强检索不是替代编辑器。它让 Claude Code 找代码更准、读代码更少但最终改代码、跑测试还是靠 Claude Code 自己的工具链。把 endpoint 配对、三件套写全、初始化指令跑一遍剩下的就是正常开发了。
