1. 启动就崩No module named mcp.server.fastmcp 到底卡在哪如果你在用 MiniMax 的 MCP 工具做联网搜索某天打开客户端突然发现工具连不上日志里甩出一行ModuleNotFoundError: No module named mcp.server.fastmcp别急着怀疑自己配置写错了。这个报错跟你的 Key、跟网络、跟客户端版本都没关系它发生在 Python 的 import 阶段——也就是说程序还没跑到发请求那一步就已经在加载模块时挂了。mcp.server.fastmcp是 MCP 官方 Python SDK 里提供 FastMCP 这个高层封装类的模块路径。MiniMax 的 MCP 工具包名minimax-coding-plan-mcp内部第 17 行就是from mcp.server.fastmcp import FastMCP。当运行环境里装的mcp包不再包含server/fastmcp这个子模块时这行 import 必然失败工具启动即退出。问题在于uvx默认在隔离环境里跑包它会按依赖声明去 PyPI 拉最新版本。而minimax-coding-plan-mcp的依赖写的是mcp[cli]1.6.0——只有下限没有上限。于是解析器很自然地拉到了破坏性的大版本旧导入路径被删报错就来了。这篇就按「定位根因 → 用 uvx 钉版本 → 配 TaoToken 通道 → 逐步验证」的顺序把工具恢复可用。适合谁看用 OpenCode、Claude Code、Cursor 等客户端接 MiniMax MCP 的开发者以及任何被uvx依赖漂移坑过、想搞懂隔离环境版本解析逻辑的人。核心检索词就三个MiniMax、MCP、uvx外加那个报错本身。2. 先搞清楚 uvx 的隔离环境与依赖解析2.1 uvx 不是「装到全局」而是每次现拉很多人对uvx有误解以为它像pip install一样把包装进系统 Python。其实uvx等价于uv tool run的行为是为这个工具创建一个临时隔离环境解析依赖、下载、执行缓存到~/.local/uv/cache或 Windows 的AppData\Local\uv\cache下。下次再跑如果缓存命中就直接用。这个设计本身很干净但有个副作用依赖解析是动态的。只要你的依赖声明没有封顶uvx每次冷启动或缓存失效后都可能拉到比上次更新的版本。上游一发大版本你的工具就可能在某天毫无征兆地崩掉。2.2 报错路径已经把答案给你了看这段报错的关键信息File C:\Users\user\AppData\Local\uv\cache\archive-v0\cache-hash\Lib\site-packages\minimax_mcp\server.py, line 17, in module from mcp.server.fastmcp import FastMCP ModuleNotFoundError: No module named mcp.server.fastmcp路径里已经明确告诉你隔离环境的site-packages在哪。进去翻一下dist-info目录你会看到类似mcp-2.0.0.dist-info mcp_types-2.0.0.dist-info装的是mcp 2.0.0。再进mcp\server\目录看只有mcpserver/、lowlevel/、auth/这些fastmcp.py或fastmcp/目录已经不存在了。MCP 官方在 2.0.0 版本里把FastMCP重命名为MCPServer并删掉了整个src/mcp/server/fastmcp/目录。官方迁移指南里「几乎每个项目都会撞到的变化」表格第一行就是这个报错。2.3 根因下游依赖没封顶上游发了破坏性大版本再看minimax-coding-plan-mcp自己的元数据Requires-Dist: mcp[cli]1.6.0只有下限1.6.0没有上限。这个下限还是 2025 年 3 月的老版本作者写完约束后就没再动过。uvx拿到这种声明自然把mcp解析到 PyPI 当前最新版——而最新版刚好变成了破坏性的 2.0.0。完整因果链是这样的minimax-coding-plan-mcp 声明 mcp[cli]1.6.0无上限 ↓ uvx 解析依赖拉到 PyPI 当前最新的 mcp 2.0.0 ↓ mcp 2.0.0 删除 mcp/server/fastmcp 模块FastMCP 改名 MCPServer ↓ minimax_mcp/server.py 第 17 行 from mcp.server.fastmcp import FastMCP 失败 ↓ ModuleNotFoundError: No module named mcp.server.fastmcp所以这不是你配置写错了也不是 MiniMax 的锅而是「上游破坏性发布 下游依赖未封顶」的经典组合。修复思路也就清晰了在 uvx 启动时注入一条2约束把 mcp 钉回 1.x。3. TaoToken 前置统一 Key 与 API 通道在动手改配置之前先把接入通道理清楚。TaoToken 提供统一的 API 入口你可以把它理解成一个「模型与工具调用的统一网关」客户端只需要认一个 Key、一个 Base URL后面接哪个模型、哪个 MCP 工具由网关侧路由。官网入口在这里https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 基础地址注意不带 UTM 参数https://taotoken.net/api你需要提前准备好的东西一个 TaoToken 账号登录后在控制台创建 API Key把 Key 存到环境变量里别硬编码进配置文件确认客户端的 MCP 配置里MINIMAX_API_KEY和MINIMAX_API_HOST这类环境变量指向你的统一通道。创建 Key 的入口在控制台的 API Keys 页面模型对话调试可以用模型对话页长期跑编码或 Agent 任务建议看 Coding Plan。这几个入口后面 CTA 会分别给出。注意MCP 工具本身是本地进程通过uvx启动它负责把工具能力暴露给客户端而模型请求走的是 API 通道。两者是分开的别把 MCP 的启动命令和 API 的 Base URL 搞混。4. 可复制配置用 --with 把 mcp 钉回 1.x4.1 核心补丁就一行不管你在哪个客户端修复的本质都是同一件事在uvx之后、包名之前插入--with和约束字符串。uvx --with mcp[cli]1.6.0,2 minimax-coding-plan-mcp --help先在命令行直接跑这条如果不再报No module named mcp.server.fastmcp说明补丁生效。--with的作用是往隔离环境里额外注入一个带约束的依赖覆盖掉原来那条没封顶的声明。mcp[cli]1.6.0,2表示要 1.6.0 以上、2.0.0 以下的版本最后稳定版 1.29.0 仍在维护fastmcp模块完整存在。4.2 OpenCode 配置配置文件在~/.config/opencode/opencode.json。原来的写法command: [uvx, minimax-coding-plan-mcp, -y]改成command: [uvx, --with, mcp[cli]1.6.0,2, minimax-coding-plan-mcp, -y]4.3 Claude Code 一键安装命令原来的命令claude mcp add -s user MiniMax \ --env MINIMAX_API_KEYyour-api-key \ --env MINIMAX_API_HOSThttps://api.minimaxi.com \ -- uvx minimax-coding-plan-mcp -y改成claude mcp add -s user MiniMax \ --env MINIMAX_API_KEYyour-api-key \ --env MINIMAX_API_HOSThttps://api.minimaxi.com \ -- uvx --with mcp[cli]1.6.0,2 minimax-coding-plan-mcp -y4.4 Claude Code 手动配置如果你改的是~/.claude.json原来的argsargs: [minimax-coding-plan-mcp, -y]改成args: [--with, mcp[cli]1.6.0,2, minimax-coding-plan-mcp, -y]4.5 Cursor 配置Cursor 的mcp.json里官方示例的args不带-y。原来args: [minimax-coding-plan-mcp]改成args: [--with, mcp[cli]1.6.0,2, minimax-coding-plan-mcp]三处改法都是同一个补丁原有的MINIMAX_API_KEY、MINIMAX_API_HOST等环境变量保留不动。改完记得重启客户端让 MCP 进程重新拉起。5. 验证请求与成功结果5.1 命令行先验证改配置前先在终端确认补丁有效uvx --with mcp[cli]1.6.0,2 minimax-coding-plan-mcp --help成功的话会打印出工具的帮助信息列出可用参数和子命令不再有 traceback。这一步过了说明版本约束生效。5.2 确认隔离环境里的 mcp 版本想更彻底一点可以进缓存目录看实际装的版本。Windows 下路径类似C:\Users\user\AppData\Local\uv\cache\archive-v0\cache-hash\Lib\site-packages\Linux/macOS 下在~/.cache/uv/或~/.local/share/uv/附近。进去后看dist-infomcp-1.29.0.dist-info只要不是 2.xmcp/server/fastmcp目录就应该在。你也可以直接列目录确认ls ~/.cache/uv/archive-v0/*/Lib/site-packages/mcp/server/看到fastmcp就对了。5.3 客户端里跑一次真实调用命令行过了之后重启客户端在对话里触发一次 MCP 工具调用比如让它做一次联网搜索。观察客户端日志如果 MCP 进程正常启动日志里会有工具注册成功的记录如果调用返回了搜索结果说明整条链路通了如果还是报模块缺失检查是不是客户端缓存了旧的启动命令或者配置改错了位置。5.4 用 TaoToken 通道做一次模型请求MCP 工具恢复后顺手验证一下 API 通道。用 curl 打一次模型对话接口curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: your-model-name, messages: [{role: user, content: ping}] }返回里有正常的choices结构说明 Key 和通道都没问题。这一步和 MCP 是两条独立的链路分开验证能快速定位问题出在哪一侧。6. 本篇常见错排查6.1 改了配置还是报同样的错最常见的原因是客户端没重启或者配置改在了错误的位置。Claude Code 有-s user和项目级两种作用域改错文件不生效。OpenCode 和 Cursor 也要确认改的是当前项目实际加载的那份配置。改完先完全退出客户端再打开。6.2 --with 参数位置放错--with必须放在uvx之后、包名之前。写成uvx minimax-coding-plan-mcp --with ...是不对的uvx会把--with当成传给工具本身的参数。正确顺序uvx --with mcp[cli]1.6.0,2 minimax-coding-plan-mcp -y6.3 约束字符串被 shell 吞掉mcp[cli]1.6.0,2里有、、[、]这些特殊字符在部分 shell 里会被解释成重定向或通配。所以一定要用引号包起来JSON 配置里本身就是字符串没问题命令行里务必加双引号。6.4 缓存里同时存在 1.x 和 2.xuvx的缓存是按 hash 分目录的旧版本可能还留着。如果怀疑缓存干扰可以清掉对应工具的缓存再跑uv cache clean minimax-coding-plan-mcp然后重新执行启动命令让它重新解析依赖。6.5 报错变成了别的模块找不到如果钉回 1.x 后出现其他 import 错误可能是mcp[cli]的 extras 没装全。确认约束字符串里带了[cli]这个 extras 会拉入命令行相关的依赖。漏掉[cli]有时会导致部分子模块缺失。6.6 长期方案等上游封顶--with是临时补丁治标。真正的修复要等minimax-coding-plan-mcp的作者把依赖声明改成mcp[cli]1.6.0,2。在那之前每次升级工具版本都要重新确认约束是否还需要。你也可以关注 MCP 官方迁移指南了解FastMCP到MCPServer的完整变更为将来升级到 2.x 做准备。7. 接入与排障入口排障和接入相关的操作建议从 API Keys 和接入文档入手先把 Key 和通道确认好API Keys 管理https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content想先验证模型是否通用模型对话页快速试一次模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content如果你是要长期跑编码任务或 Agent建议直接看 Coding Plan把额度和通道一次配好Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentClaude Code 用户还可以参考 Anthropic 兼容接入的说明ClaudeCodeAnthropichttps://taotoken.net/doc/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content最后留一个我自己的习惯把uvx --with mcp[cli]1.6.0,2这段约束写进一个 shell 别名或者项目脚本里别每次手敲。依赖漂移这种事只要上游没封顶就还会再来一次把补丁固化下来能省不少排查时间。
MiniMax MCP 工具报 No module named mcp.server.fastmcp：用 uvx 配 TaoToken 的排查与修复
1. 启动就崩No module named mcp.server.fastmcp 到底卡在哪如果你在用 MiniMax 的 MCP 工具做联网搜索某天打开客户端突然发现工具连不上日志里甩出一行ModuleNotFoundError: No module named mcp.server.fastmcp别急着怀疑自己配置写错了。这个报错跟你的 Key、跟网络、跟客户端版本都没关系它发生在 Python 的 import 阶段——也就是说程序还没跑到发请求那一步就已经在加载模块时挂了。mcp.server.fastmcp是 MCP 官方 Python SDK 里提供 FastMCP 这个高层封装类的模块路径。MiniMax 的 MCP 工具包名minimax-coding-plan-mcp内部第 17 行就是from mcp.server.fastmcp import FastMCP。当运行环境里装的mcp包不再包含server/fastmcp这个子模块时这行 import 必然失败工具启动即退出。问题在于uvx默认在隔离环境里跑包它会按依赖声明去 PyPI 拉最新版本。而minimax-coding-plan-mcp的依赖写的是mcp[cli]1.6.0——只有下限没有上限。于是解析器很自然地拉到了破坏性的大版本旧导入路径被删报错就来了。这篇就按「定位根因 → 用 uvx 钉版本 → 配 TaoToken 通道 → 逐步验证」的顺序把工具恢复可用。适合谁看用 OpenCode、Claude Code、Cursor 等客户端接 MiniMax MCP 的开发者以及任何被uvx依赖漂移坑过、想搞懂隔离环境版本解析逻辑的人。核心检索词就三个MiniMax、MCP、uvx外加那个报错本身。2. 先搞清楚 uvx 的隔离环境与依赖解析2.1 uvx 不是「装到全局」而是每次现拉很多人对uvx有误解以为它像pip install一样把包装进系统 Python。其实uvx等价于uv tool run的行为是为这个工具创建一个临时隔离环境解析依赖、下载、执行缓存到~/.local/uv/cache或 Windows 的AppData\Local\uv\cache下。下次再跑如果缓存命中就直接用。这个设计本身很干净但有个副作用依赖解析是动态的。只要你的依赖声明没有封顶uvx每次冷启动或缓存失效后都可能拉到比上次更新的版本。上游一发大版本你的工具就可能在某天毫无征兆地崩掉。2.2 报错路径已经把答案给你了看这段报错的关键信息File C:\Users\user\AppData\Local\uv\cache\archive-v0\cache-hash\Lib\site-packages\minimax_mcp\server.py, line 17, in module from mcp.server.fastmcp import FastMCP ModuleNotFoundError: No module named mcp.server.fastmcp路径里已经明确告诉你隔离环境的site-packages在哪。进去翻一下dist-info目录你会看到类似mcp-2.0.0.dist-info mcp_types-2.0.0.dist-info装的是mcp 2.0.0。再进mcp\server\目录看只有mcpserver/、lowlevel/、auth/这些fastmcp.py或fastmcp/目录已经不存在了。MCP 官方在 2.0.0 版本里把FastMCP重命名为MCPServer并删掉了整个src/mcp/server/fastmcp/目录。官方迁移指南里「几乎每个项目都会撞到的变化」表格第一行就是这个报错。2.3 根因下游依赖没封顶上游发了破坏性大版本再看minimax-coding-plan-mcp自己的元数据Requires-Dist: mcp[cli]1.6.0只有下限1.6.0没有上限。这个下限还是 2025 年 3 月的老版本作者写完约束后就没再动过。uvx拿到这种声明自然把mcp解析到 PyPI 当前最新版——而最新版刚好变成了破坏性的 2.0.0。完整因果链是这样的minimax-coding-plan-mcp 声明 mcp[cli]1.6.0无上限 ↓ uvx 解析依赖拉到 PyPI 当前最新的 mcp 2.0.0 ↓ mcp 2.0.0 删除 mcp/server/fastmcp 模块FastMCP 改名 MCPServer ↓ minimax_mcp/server.py 第 17 行 from mcp.server.fastmcp import FastMCP 失败 ↓ ModuleNotFoundError: No module named mcp.server.fastmcp所以这不是你配置写错了也不是 MiniMax 的锅而是「上游破坏性发布 下游依赖未封顶」的经典组合。修复思路也就清晰了在 uvx 启动时注入一条2约束把 mcp 钉回 1.x。3. TaoToken 前置统一 Key 与 API 通道在动手改配置之前先把接入通道理清楚。TaoToken 提供统一的 API 入口你可以把它理解成一个「模型与工具调用的统一网关」客户端只需要认一个 Key、一个 Base URL后面接哪个模型、哪个 MCP 工具由网关侧路由。官网入口在这里https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 基础地址注意不带 UTM 参数https://taotoken.net/api你需要提前准备好的东西一个 TaoToken 账号登录后在控制台创建 API Key把 Key 存到环境变量里别硬编码进配置文件确认客户端的 MCP 配置里MINIMAX_API_KEY和MINIMAX_API_HOST这类环境变量指向你的统一通道。创建 Key 的入口在控制台的 API Keys 页面模型对话调试可以用模型对话页长期跑编码或 Agent 任务建议看 Coding Plan。这几个入口后面 CTA 会分别给出。注意MCP 工具本身是本地进程通过uvx启动它负责把工具能力暴露给客户端而模型请求走的是 API 通道。两者是分开的别把 MCP 的启动命令和 API 的 Base URL 搞混。4. 可复制配置用 --with 把 mcp 钉回 1.x4.1 核心补丁就一行不管你在哪个客户端修复的本质都是同一件事在uvx之后、包名之前插入--with和约束字符串。uvx --with mcp[cli]1.6.0,2 minimax-coding-plan-mcp --help先在命令行直接跑这条如果不再报No module named mcp.server.fastmcp说明补丁生效。--with的作用是往隔离环境里额外注入一个带约束的依赖覆盖掉原来那条没封顶的声明。mcp[cli]1.6.0,2表示要 1.6.0 以上、2.0.0 以下的版本最后稳定版 1.29.0 仍在维护fastmcp模块完整存在。4.2 OpenCode 配置配置文件在~/.config/opencode/opencode.json。原来的写法command: [uvx, minimax-coding-plan-mcp, -y]改成command: [uvx, --with, mcp[cli]1.6.0,2, minimax-coding-plan-mcp, -y]4.3 Claude Code 一键安装命令原来的命令claude mcp add -s user MiniMax \ --env MINIMAX_API_KEYyour-api-key \ --env MINIMAX_API_HOSThttps://api.minimaxi.com \ -- uvx minimax-coding-plan-mcp -y改成claude mcp add -s user MiniMax \ --env MINIMAX_API_KEYyour-api-key \ --env MINIMAX_API_HOSThttps://api.minimaxi.com \ -- uvx --with mcp[cli]1.6.0,2 minimax-coding-plan-mcp -y4.4 Claude Code 手动配置如果你改的是~/.claude.json原来的argsargs: [minimax-coding-plan-mcp, -y]改成args: [--with, mcp[cli]1.6.0,2, minimax-coding-plan-mcp, -y]4.5 Cursor 配置Cursor 的mcp.json里官方示例的args不带-y。原来args: [minimax-coding-plan-mcp]改成args: [--with, mcp[cli]1.6.0,2, minimax-coding-plan-mcp]三处改法都是同一个补丁原有的MINIMAX_API_KEY、MINIMAX_API_HOST等环境变量保留不动。改完记得重启客户端让 MCP 进程重新拉起。5. 验证请求与成功结果5.1 命令行先验证改配置前先在终端确认补丁有效uvx --with mcp[cli]1.6.0,2 minimax-coding-plan-mcp --help成功的话会打印出工具的帮助信息列出可用参数和子命令不再有 traceback。这一步过了说明版本约束生效。5.2 确认隔离环境里的 mcp 版本想更彻底一点可以进缓存目录看实际装的版本。Windows 下路径类似C:\Users\user\AppData\Local\uv\cache\archive-v0\cache-hash\Lib\site-packages\Linux/macOS 下在~/.cache/uv/或~/.local/share/uv/附近。进去后看dist-infomcp-1.29.0.dist-info只要不是 2.xmcp/server/fastmcp目录就应该在。你也可以直接列目录确认ls ~/.cache/uv/archive-v0/*/Lib/site-packages/mcp/server/看到fastmcp就对了。5.3 客户端里跑一次真实调用命令行过了之后重启客户端在对话里触发一次 MCP 工具调用比如让它做一次联网搜索。观察客户端日志如果 MCP 进程正常启动日志里会有工具注册成功的记录如果调用返回了搜索结果说明整条链路通了如果还是报模块缺失检查是不是客户端缓存了旧的启动命令或者配置改错了位置。5.4 用 TaoToken 通道做一次模型请求MCP 工具恢复后顺手验证一下 API 通道。用 curl 打一次模型对话接口curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: your-model-name, messages: [{role: user, content: ping}] }返回里有正常的choices结构说明 Key 和通道都没问题。这一步和 MCP 是两条独立的链路分开验证能快速定位问题出在哪一侧。6. 本篇常见错排查6.1 改了配置还是报同样的错最常见的原因是客户端没重启或者配置改在了错误的位置。Claude Code 有-s user和项目级两种作用域改错文件不生效。OpenCode 和 Cursor 也要确认改的是当前项目实际加载的那份配置。改完先完全退出客户端再打开。6.2 --with 参数位置放错--with必须放在uvx之后、包名之前。写成uvx minimax-coding-plan-mcp --with ...是不对的uvx会把--with当成传给工具本身的参数。正确顺序uvx --with mcp[cli]1.6.0,2 minimax-coding-plan-mcp -y6.3 约束字符串被 shell 吞掉mcp[cli]1.6.0,2里有、、[、]这些特殊字符在部分 shell 里会被解释成重定向或通配。所以一定要用引号包起来JSON 配置里本身就是字符串没问题命令行里务必加双引号。6.4 缓存里同时存在 1.x 和 2.xuvx的缓存是按 hash 分目录的旧版本可能还留着。如果怀疑缓存干扰可以清掉对应工具的缓存再跑uv cache clean minimax-coding-plan-mcp然后重新执行启动命令让它重新解析依赖。6.5 报错变成了别的模块找不到如果钉回 1.x 后出现其他 import 错误可能是mcp[cli]的 extras 没装全。确认约束字符串里带了[cli]这个 extras 会拉入命令行相关的依赖。漏掉[cli]有时会导致部分子模块缺失。6.6 长期方案等上游封顶--with是临时补丁治标。真正的修复要等minimax-coding-plan-mcp的作者把依赖声明改成mcp[cli]1.6.0,2。在那之前每次升级工具版本都要重新确认约束是否还需要。你也可以关注 MCP 官方迁移指南了解FastMCP到MCPServer的完整变更为将来升级到 2.x 做准备。7. 接入与排障入口排障和接入相关的操作建议从 API Keys 和接入文档入手先把 Key 和通道确认好API Keys 管理https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content想先验证模型是否通用模型对话页快速试一次模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content如果你是要长期跑编码任务或 Agent建议直接看 Coding Plan把额度和通道一次配好Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentClaude Code 用户还可以参考 Anthropic 兼容接入的说明ClaudeCodeAnthropichttps://taotoken.net/doc/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content最后留一个我自己的习惯把uvx --with mcp[cli]1.6.0,2这段约束写进一个 shell 别名或者项目脚本里别每次手敲。依赖漂移这种事只要上游没封顶就还会再来一次把补丁固化下来能省不少排查时间。
