1. Windows 下 Claude Code 接入 Serena MCP 时 uvx 报 unknown option '--from' 的完整排查

Claude Code 是 Anthropic 推出的命令行编码助手，Serena MCP 则是一个基于 LSP 的语义代码检索服务，两者组合后能让 Claude Code 在大型仓库里做符号级跳转、引用查找和跨文件重构。问题出在 Windows 上：很多人在 PowerShell 里执行claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server ...，终端立刻回一句error: unknown option '--from'，MCP 服务根本没注册上。这个报错不是 Serena 的问题，也不是 uvx 装错了，而是 PowerShell 对--from这类参数做了自己的解析，把它当成 PowerShell 的保留选项吞掉了，真正传给 uvx 的参数已经变形。

我试过在 PowerShell 7 和 Windows Terminal 默认配置下复现，报错稳定出现；切到传统 cmd 后同一条命令一次通过。所以这篇的核心结论先给出来：在 Windows 上注册 Serena MCP，请用 cmd，不要用 PowerShell。下面会把 uvx 版本检查、cmd 可复制命令、Serena MCP 配置片段、以及把 endpoint 切到 TaoToken 统一通道后的连通性验证，一步步写清楚。适合已经在用 Claude Code、想加语义检索能力、但被 Windows 终端差异卡住的开发者。读完后你能拿到一份可直接粘贴的 cmd 命令，并知道每一步在验证什么。

需要先明确一点：uvx是 uv 工具链提供的临时执行入口，它会去拉取git+https://github.com/oraios/serena这个源，再以serena start-mcp-server启动 MCP 服务。--from是 uvx 用来指定包来源的合法参数，uvx 本身完全支持。问题只在于谁来解析这行命令。PowerShell 会把--from当作自己的参数候选，导致 uvx 收到的是残缺参数，于是 uv 的 CLI 解析器抛出 unknown option。cmd 不做这种预处理，参数原样透传，所以能成功。理解这一点，后面所有排障都围绕“让参数原样到达 uvx”展开。

2. TaoToken 前置准备：统一 Key 与 API 通道

在动手注册 MCP 之前，先把模型侧的通道准备好，否则 Serena 注册成功、Claude Code 也连上了，但真正发起模型请求时仍会因为 endpoint 和 Key 不统一而失败。TaoToken 在这里的角色是提供一个统一的 API 入口，把 Claude Code 的模型请求收敛到一个 Base URL 和一把 Key 上，省去在多个配置文件中来回改地址的麻烦。官网入口是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 基址是 https://taotoken.net/api 。

你需要先拿到两样东西：一把 API Key，以及确认要用的 Model ID。Key 在控制台的 API Keys 页面创建，地址是 https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。创建时建议按用途命名，比如claude-code-serena，方便以后区分和吊销。Model ID 则取决于你打算让 Claude Code 走哪个模型，常见的是 Claude 系列，具体以控制台或文档里列出的为准。文档入口在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有 Base URL、鉴权头和可用模型的说明。

这里要强调“三件套”必须同时对齐：Base URL、API Key、Model ID。任何一件缺失或写错，表现都可能是 401 或连接被拒。Base URL 用https://taotoken.net/api，注意不要多加路径后缀；Key 用刚才创建的那把；Model ID 用文档里确认过的字符串。把这三样先记在记事本里，下一步写配置时会直接用到。如果你更想先验证模型通道本身是否通，可以打开模型对话页面 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 发一条测试消息，确认 Key 有效后再去折腾 MCP，这样能把“模型通道问题”和“MCP 注册问题”分开定位。

对于长期在 Claude Code 里做编码和 Agent 任务的场景，可以考虑 Coding Plan，入口是 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，它更适合高频调用。但无论用哪种方式，Base URL 和 Key 的写法是一致的，下面配置片段里会体现。

3. 可复制配置：cmd 注册命令与 Serena MCP 配置片段

这一节是全文最需要照着做的部分。先确认 uvx 可用，再在 cmd 里注册，最后写配置文件。顺序不要颠倒，否则报错来源会混在一起。

3.1 检查 uvx 版本与可用性

打开 cmd（不是 PowerShell），执行：

uvx --version uv --version

正常会输出类似uvx 0.4.x和uv 0.4.x的版本号。如果提示'uvx' 不是内部或外部命令，说明 uv 没装或没进 PATH。可以用官方安装脚本装 uv，装完重开一个 cmd 窗口让 PATH 生效。版本不必追求最新，但建议不低于 0.4，早期版本对--from的处理和 git 源支持略有差异。确认uvx --version有输出，再往下走。

3.2 在 cmd 中注册 Serena MCP

关键点：整条命令在 cmd 里执行，--from原样传给 uvx。可复制命令如下：

claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context ide-assistant --project %CD%

注意这里把 PowerShell 里的$(pwd)换成了 cmd 的%CD%，表示当前目录。如果你要固定到某个项目路径，直接写绝对路径，例如--project D:\work\myrepo。执行后 Claude Code 会把 serena 这个 MCP server 写进它的配置。可以用下面的命令确认注册结果：

claude mcp list

看到serena出现在列表里，且命令部分包含uvx --from git+https://github.com/oraios/serena，说明注册成功。如果列表里没有，或者命令被截断，多半是又跑回 PowerShell 了，回到 cmd 重来。

3.3 Serena MCP 配置片段（JSON）

Claude Code 的 MCP 配置通常落在用户目录下的配置文件中。Windows 上常见路径是C:\Users\<你的用户名>\.claude.json或项目内的.mcp.json。如果你倾向手写而不是用claude mcp add，可以写入如下 JSON 片段：

{ "mcpServers": { "serena": { "command": "uvx", "args": [ "--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--context", "ide-assistant", "--project", "D:\\work\\myrepo" ] } } }

路径里的反斜杠要写成双反斜杠，这是 JSON 转义要求。command用uvx，args数组里第一个就是--from，这样即使不经过 shell，参数也不会被 PowerShell 改写。手写配置的好处是可控，坏处是路径和转义容易错，改完记得用claude mcp list复核。

3.4 把 endpoint 指向 TaoToken 统一通道

模型侧的配置同样要落到文件里。Claude Code 读取的模型配置一般通过环境变量或 settings 文件注入。推荐用 settings 片段，把 Base URL、Key、Model ID 三件套写全：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的TaoTokenKey", "ANTHROPIC_MODEL": "你的ModelID" } }

把sk-你的TaoTokenKey换成控制台创建的那把 Key，你的ModelID换成文档里确认的模型标识。Base URL 保持https://taotoken.net/api，不要追加/v1之类后缀，除非文档明确要求。写完后重启 Claude Code，让环境变量生效。这一步做完，Serena 负责代码语义，TaoToken 负责模型通道，两条链路就都齐了。

4. 验证请求：从 MCP 列表到一次真实调用

配置写完不等于通了，必须做连通性验证。验证分两层：先确认 MCP 服务能起来，再确认模型请求能走通。

第一层，在 cmd 里直接手动拉起 Serena，看它是否能启动而不报参数错误：

uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context ide-assistant --project %CD%

如果这条命令能进入服务等待状态、没有unknown option '--from'，说明 uvx 和参数都没问题。按 Ctrl+C 退出，再回到 Claude Code 里用claude mcp list确认注册项存在。这一步排除了“命令本身写错”的可能。

第二层，在 Claude Code 会话里触发一次需要 Serena 的语义检索，比如让它查找某个函数的引用。观察输出：如果 Claude Code 能调用到 serena 工具并返回符号结果，说明 MCP 链路通。此时如果模型请求失败，报错通常出现在模型调用阶段，而不是 MCP 阶段，两者要分开看。

第三层，单独验证 TaoToken 通道。可以用 curl 在 cmd 里发一条最小请求：

curl -X POST https://taotoken.net/api/v1/messages ^ -H "x-api-key: sk-你的TaoTokenKey" ^ -H "anthropic-version: 2023-06-01" ^ -H "content-type: application/json" ^ -d "{\"model\":\"你的ModelID\",\"max_tokens\":64,\"messages\":[{\"role\":\"user\",\"content\":\"ping\"}]}"

注意 cmd 里换行用^，JSON 里的引号要转义。如果返回包含content的正常响应，说明 Key、Base URL、Model ID 三件套正确。若返回 401，检查 Key 是否复制完整、是否有多余空格；若返回模型不存在，检查 Model ID 拼写。把这一层单独验通，再回到 Claude Code 里跑完整流程，定位效率会高很多。

5. 本篇常见错排查：unknown option、401 与 local proxy failed

排障时先看报错原文，不同报错指向不同层。下面按真实出现频率排列。

error: unknown option '--from'：几乎可以断定是在 PowerShell 里执行的。解决方式是切到 cmd 重跑注册命令，或者改用手写 JSON 配置绕过 shell 解析。判断方法很简单，看当前终端提示符是PS C:\...>还是C:\...>，前者是 PowerShell。也可以在命令前加cmd /c强制走 cmd，但更推荐直接开一个 cmd 窗口，避免嵌套引号问题。

401 Unauthorized：模型通道鉴权失败。检查ANTHROPIC_API_KEY是否是 TaoToken 控制台创建的那把，有没有把 Key 写进错误的配置文件，或者环境变量被旧值覆盖。Windows 上环境变量分用户级和系统级，改完要重开终端。如果用的是 settings 文件，确认 JSON 没有语法错误导致整段被忽略。

local proxy failed或连接被拒：通常是 Base URL 写错，比如多写了路径、少了协议头，或者本地网络策略拦截。确认ANTHROPIC_BASE_URL是https://taotoken.net/api，用第 4 节的 curl 单独验证一次。如果 curl 通而 Claude Code 不通，问题在 Claude Code 的配置加载，检查配置文件路径和优先级。

reading choices类解析错误：多出现在响应体不是预期 JSON 时，比如把 HTML 错误页当成 API 返回。用 curl 看原始响应，确认返回的是 JSON 而不是网关错误页。这类问题往往和 Base URL 或鉴权头有关，回到三件套逐项核对。

OAuth 相关报错：如果 Claude Code 提示需要登录或 OAuth 流程，说明它没走 API Key 模式，而是尝试了账号登录。确认配置里用的是ANTHROPIC_API_KEY而不是登录态，必要时清理旧的凭据缓存再重启。CC Switch、Cline MCP、Codex 的auth.json这类工具如果同时存在，注意它们各自的 Base URL、Key、Model ID 是否一致，避免互相覆盖。任何一处只写了 Base URL 没写 Key 或 Model ID，都会表现为鉴权或模型错误。

排查顺序建议固定为：先确认终端是 cmd，再确认 uvx 版本，再确认 MCP 注册项，最后确认模型三件套。按这个顺序走，绝大多数报错都能在五分钟内定位到具体一层。

6. 继续用下去：把 Serena 与 TaoToken 通道固定成日常配置

Serena 注册成功后，日常使用中真正影响体验的是配置的稳定性。建议把项目路径写死而不是依赖%CD%，这样无论从哪个目录启动 Claude Code，Serena 都能索引到正确的仓库。多项目场景可以注册多个 MCP 条目，比如serena-work和serena-side，各自指向不同--project路径，避免索引串味。

模型通道这边，把 Base URL、Key、Model ID 三件套集中放在一个 settings 文件里，不要散落在多个环境变量和工具配置中。需要换模型时只改一处，减少 401 和模型不存在的排查成本。Key 建议定期在控制台轮换，旧 Key 及时吊销。如果调用频率高，Coding Plan 入口在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，API Keys 管理在 https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。需要快速验证模型是否可用时，模型对话页面 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 是最省事的入口。

最后留一个实操习惯：每次改完 MCP 或模型配置，先跑claude mcp list，再用 curl 打一条最小请求，两个都过再进 Claude Code 干活。这样能把问题挡在会话之外，而不是在编码中途被打断。