1. Windows 下 Claude Code 配置 MCP 的真实痛点Claude Code 在 Windows 上接入 MCPModel Context Protocol服务器本质是让 Claude Code 通过 stdio 或 HTTP 协议去调用外部工具进程。听起来简单但 Windows 的进程模型、环境变量继承、路径分隔符和 shell 差异会让uvx和npx这两条最常见的启动链路频繁翻车。你大概率遇到过这几种情况在 PowerShell 里敲uvx mcp-server-fetch明明能跑写进.claude.json后 Claude Code 却报command not found或者npx启动时卡在local proxy failed、reading choices之类的错误上再或者 MCP 状态显示 connected 但一调用工具就超时。这些问题的根因通常不在 MCP 服务器本身而在三件事可执行文件是否在 Claude Code 继承的 PATH 里、stdio 类型是否用cmd /c正确包装、网络出口是否稳定可达。前两个是 Windows 特有的坑第三个则决定了你调用模型和工具时的成功率。这篇就按“先排障、再统一接入”的顺序把 uvx 与 npx 启动失败逐条拆开最后把 endpoint 收敛到 TaoToken 的统一 Key/API 通道目标是一次跑通本地 MCP 服务。适合谁看已经在 Windows 上装了 Claude Code、想接 fetch/time/git 这类 MCP 工具、但被启动报错卡住的开发者。你不需要精通 Node 或 Python 包管理跟着配置片段改就行。先说清楚一个概念避免后面混淆。MCP 服务器分两类传输方式stdio本地进程Claude Code 通过标准输入输出通信和HTTP/SSE远程服务。Windows 上出问题的几乎都是 stdio 类型因为它依赖 Claude Code 去 spawn 一个子进程而子进程能不能找到uvx/npx、能不能正确解析参数全看你的配置写法。下面所有排查都围绕 stdio 展开。2. TaoToken 前置统一 Key 与 API 通道准备在动手改 MCP 配置之前先把模型侧的通道理顺。很多人 MCP 配好了结果 Claude Code 请求模型时因为 endpoint 或 Key 的问题失败误以为是 MCP 的锅。TaoToken 在这里的作用是提供一个统一的 API 入口和 Key 管理让你不用在多个供应商之间来回切换配置。你需要准备两样东西一个可用的 API Key以及确认 Base URL 指向https://taotoken.net/api。注意 API 地址不带任何查询参数保持干净。Key 的获取在控制台的 API Keys 页面完成登录后新建一个 Key 即可建议按用途命名比如claude-code-win方便后续轮换。拿到 Key 后Claude Code 侧有两种接入方式。一种是走环境变量在启动 Claude Code 的终端里设置ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN或对应变量这样 Claude Code 的所有模型请求都会走 TaoToken 通道。另一种是在 Claude Code 的配置文件里写死。我建议用环境变量因为改起来不用动 JSON排障时也容易临时切换。这里要强调一个顺序问题先确认模型通道通了再配 MCP。否则 MCP 报错和模型报错混在一起你根本分不清是哪一层的问题。验证模型通道最简单的办法是直接在 Claude Code 里发一句普通对话能正常返回就说明 Key 和 endpoint 没问题。如果这一步就失败先别碰 MCP回去检查 Key 是否复制完整、Base URL 是否写成了带路径的错误形式。对于需要长期跑编码任务或 Agent 的场景可以考虑用 Coding Plan 这类套餐来管理额度避免按次调用时频繁触发限流。但这是后话当前阶段你只需要一个能用的 Key 和正确的 Base URL。把这两样记下来下一步配置 MCP 时会反复用到。顺便提一句TaoToken 的接入文档里有各语言/工具的示例遇到变量名不确定时可以去对照比在群里问快。文档入口在官网导航里能找到这里不展开。3. 可复制配置settings 与 .claude.json 片段这一节是核心直接给可复制的配置。先明确文件位置Windows 上 Claude Code 的全局配置通常在C:\Users\你的用户名\.claude.json。不同安装方式可能略有差异如果这个路径下没有可以在 Claude Code 里用/config或查看启动日志确认实际加载的文件。所有 MCP 服务器都配在这个文件的mcpServers对象里。先解决uvx找不到的问题。uv 安装后uvx.exe一般在C:\Users\你的用户名\.local\bin。这个目录默认不在系统 PATH 里所以 Claude Code spawn 子进程时找不到它。有两种修法一是把这个目录加进系统环境变量 PATH 并重启终端二是在配置里写绝对路径。我更推荐第二种因为它不依赖全局环境换机器也好迁移。下面是一个完整的mcpServers片段包含 fetch、time、git 三个常用服务全部用cmd /c包装这是 Windows 上 stdio 类型的关键写法{ mcpServers: { fetch: { type: stdio, command: cmd, args: [ /c, uvx, mcp-server-fetch, --ignore-robots-txt ] }, time: { type: stdio, command: cmd, args: [ /c, npx, -y, guanxiong/mcp-server-time ] }, mcp-server-git: { type: stdio, command: cmd, args: [ /c, uvx, mcp-server-git ] } } }几个细节必须说清楚。第一cmd /c的作用是让 Windows 用命令解释器去解析后面的命令这样uvx和npx才能被正确找到并执行。不加cmd /c直接写uvx在部分 Claude Code 版本里会直接报 spawn 失败。第二npx建议加-y参数避免首次运行时弹出交互式确认卡住进程。第三--ignore-robots-txt是 fetch 的可选参数个人使用想抓取被 robots 限制的页面时加上团队合规场景建议去掉。如果你想把 uvx 写成绝对路径把uvx换成C:\\Users\\你的用户名\\.local\\bin\\uvx.exe即可注意 JSON 里反斜杠要转义。npx 同理通常在 Node 安装目录下。关于模型通道的配置如果你选择在 settings 里写Claude Code 支持在配置中指定环境变量。一个常见的做法是在.claude.json同级或项目内的 settings 文件里加{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: 你的TaoToken Key } }注意变量名要以你实际使用的 Claude Code 版本为准有的版本用ANTHROPIC_API_KEY。不确定时优先用环境变量方式在 PowerShell 里$env:ANTHROPIC_BASE_URLhttps://taotoken.net/api这样设置然后从同一个终端启动 Claude Code子进程会继承。配置改完后必须重启 Claude Code因为mcpServers是在启动时读取的。重启后在对话里输入/mcp能看到服务列表和状态。如果某个服务显示 failed先别急着改配置看下一节的验证方法。4. 验证请求与成功结果配置写完不代表跑通得逐步验证。我习惯分三层验证命令行层、Claude Code 层、工具调用层。任何一层失败都能快速定位。第一层命令行直接跑。打开 PowerShell先确认 uvx 可用uv --version uvx --version如果uvx报不是内部或外部命令说明 PATH 没配好回到上一节用绝对路径。然后直接跑一次 fetch 服务uvx mcp-server-fetch正常的话它会启动并等待输入光标停住不返回这说明服务本身能起来。按 CtrlC 退出。这一步能过说明包下载和运行没问题问题只可能在 Claude Code 的 spawn 环节。第二层验证 npx 链路npx -y guanxiong/mcp-server-time首次运行会从 npm 拉包稍等几秒。同样会停住等待输入CtrlC 退出。如果这里报网络错误或 404检查 npm 源和网络出口。第三层回到 Claude Code。重启后输入/mcp应该看到类似这样的输出每个服务名后面跟着 connected 或 ready 状态。如果显示 connected就可以实际调用工具了。测试 fetch让 Claude Code “读取 https://example.com 并总结”它会调用 fetch 工具返回网页内容摘要。测试 time问“现在温哥华几点”它会调用get_current_time并带上时区参数返回准确时间。测试 git在一个 git 仓库目录下问“当前有哪些未提交的改动”它会调用git_status。成功的结果长这样工具调用有明确的返回不是超时或空响应。如果/mcp显示 connected 但调用工具报错多半是参数或权限问题比如 git 服务需要你在仓库目录下启动 Claude Code。关于模型通道的验证可以在 Claude Code 里发一句需要推理的问题观察响应速度。走 TaoToken 通道时如果 Key 或 Base URL 有问题会直接返回 401 或连接错误而不是 MCP 层的报错。把这两类错误区分开排障效率会高很多。5. 本篇常见错误排查这一节按真实报错来对照遇到哪个查哪个。报错一command not found: uvx或 spawn uvx ENOENT。这是最高频的。原因就是 Claude Code 继承的 PATH 里没有 uvx 所在目录。解决配置里用cmd /c包装或写 uvx 绝对路径。改完重启 Claude Code。注意你在 PowerShell 里能跑 uvx不代表 Claude Code 能跑因为 GUI 启动的进程和终端启动的进程 PATH 可能不同。报错二local proxy failed或连接超时。这类错误通常出现在模型请求层不是 MCP 层。检查ANTHROPIC_BASE_URL是否写成了https://taotoken.net/api有没有多写斜杠或路径。Key 是否过期或被禁用。如果用了环境变量确认启动 Claude Code 的终端里变量确实生效了可以用echo $env:ANTHROPIC_BASE_URL验证。报错三reading choices或 npx 卡住不动。这是 npx 在等交互式确认。加-y参数即可。另外首次拉包慢也会表现为卡住耐心等或先手动跑一次npx -y 包名把缓存预热。报错四401 Unauthorized。Key 错误或没带上。检查 Key 是否复制完整前后无空格变量名是否和 Claude Code 版本匹配。有的版本读ANTHROPIC_AUTH_TOKEN有的读ANTHROPIC_API_KEY两个都试一下。走 TaoToken 通道时Key 从控制台的 API Keys 页面获取确认状态是启用。报错五OAuth 相关错误。如果你之前用官方账号登录过配置里可能残留 OAuth 凭据和 API Key 模式冲突。清理掉旧的认证信息确保只走 Key 模式。具体清理位置在.claude.json的认证字段或系统凭据管理器里。报错六MCP 显示 connected 但工具调用无响应。常见于 git 服务不在仓库目录、fetch 被 robots 拦截、time 时区参数写错。逐个排除git 在仓库根目录启动 Claude Codefetch 加--ignore-robots-txttime 明确指定时区名如America/Vancouver。报错七改了配置不生效。Claude Code 不会热加载mcpServers必须完全退出再启动。任务管理器里确认没有残留进程。排查时有个通用技巧把 MCP 服务的启动命令单独在终端跑一遍看它自己报什么错。终端能跑通、Claude Code 跑不通问题一定在 spawn 环境或配置写法终端也跑不通问题在包本身或网络。6. 语义一致 CTA 与后续建议配置跑通后日常使用中还有几个习惯能减少返工。第一Key 定期轮换在控制台的 API Keys 页面新建再删旧避免一个 Key 用到底。第二MCP 服务按需开启不用的从mcpServers里注释掉减少启动时的 spawn 开销和潜在冲突。第三把验证过的配置片段存一份到自己的笔记里换机器时直接复制比重新踩坑快得多。如果你在排障过程中需要确认某个接口的调用方式接入文档里有各场景的示例对照着改比猜变量名靠谱。需要新建或管理 Key 时直接去 API Keys 页面操作。想先验证模型通道是否正常可以在模型对话里发一句测试确认返回正常再回去配 MCP。对于需要长期跑编码任务、频繁调用工具的场景Coding Plan 能帮你把额度管理得更省心不用每次担心限流。最后说一个我踩过的坑Windows 上路径里的用户名如果包含中文或空格uvx 和 npx 的缓存路径可能出问题。遇到莫名其妙的启动失败先把 uv 缓存目录和 npm 缓存目录换到纯英文无空格路径下比如C:\dev\cache很多玄学问题会消失。这个不在配置片段里体现但值得记一笔。