故障排除

本部分列出了使用 MiniMax-MCP 服务器时可能遇到的一些常见问题及其解决方法。

常见问题 (FAQ)

1. 错误: invalid api key 或 API Error: invalid api key

• 症状: 在客户端调用 MiniMax 工具时收到此错误。
• 原因: 您配置的 API 密钥 (MINIMAX_API_KEY) 与 API 主机 (MINIMAX_API_HOST) 的区域不匹配。
• 解决方法:
  1. 确认您获取 API 密钥的 MiniMax 平台区域（全球 Global 或中国大陆 Mainland）。
  2. 确保您在客户端配置中使用的 MINIMAX_API_HOST 是与该区域对应的正确主机地址。
  3. 请参考 快速开始 - 区域差异 部分获取正确的区域和主机对应关系。

来源：README.md

2. 错误: spawn uvx ENOENT (或其他类似 'command not found' 错误)

• 症状: 客户端无法启动 MiniMax-MCP 服务器，日志中显示类似 ENOENT (Error NO ENTity/File) 的错误。
• 原因: 客户端在其执行环境中找不到 uvx 命令。
• 解决方法:
  1. 在您的终端（确保 uv 已正确安装并配置在 PATH 中）运行 which uvx 命令，获取 uvx 可执行文件的 绝对路径 (例如 /home/user/.local/bin/uvx 或 /usr/local/bin/uvx)。
  2. 修改您在客户端（如 Claude Desktop, Cursor）中的 MiniMax-MCP 服务器配置，将 command 字段的值从 "uvx" 更改为获取到的绝对路径，例如 "command": "/home/user/.local/bin/uvx"。

来源：README.md

3. generate_video 调用后没有立即看到结果?

• 症状: 调用 generate_video 工具后，客户端只收到了一个 task_id，没有视频文件。
• 原因: generate_video 是一个 异步 操作。视频生成需要时间，服务器不会阻塞等待完成，而是立即返回一个任务 ID 让您可以稍后查询结果。
• 解决方法:
  1. 记录 generate_video 返回的 task_id。
  2. 使用 query_video_generation 工具，并提供该 task_id 来查询任务状态。
  3. 您可能需要多次调用 query_video_generation，直到状态变为 completed。
  4. 任务完成后，query_video_generation 的响应将包含视频文件的 URL 或本地路径。
  5. 或者: 利用客户端的完成规则 (Completion Rules) 功能（如果支持，如 Cursor），让客户端自动处理这个查询流程。

来源：README.md

4. 生成的文件保存在哪里了？ (当 MINIMAX_API_RESOURCE_MODE=local)

• 症状: 配置了 MINIMAX_API_RESOURCE_MODE=local，但不确定生成的文件（音频、图像、视频）存储在何处。
• 原因: 文件被下载到了 MINIMAX_MCP_BASE_PATH 环境变量指定的目录中。
• 解决方法:
  1. 检查您在客户端配置中为 MINIMAX_MCP_BASE_PATH 设置的值。
  2. 确保该目录存在，并且运行 MCP 服务器的进程具有对该目录的写入权限。
  3. 生成的文件应该位于该目录下。

来源：README.md

错误码说明

(目前没有详细的错误码列表。当遇到未在上面列出的错误时，建议：) 1. 仔细阅读客户端或服务器日志中返回的完整错误消息。 2. 检查 MiniMax 官方 API 文档，看是否有相关的错误码说明。 3. 检查您的工具调用参数是否符合 API 要求。

性能优化

(目前没有具体的性能优化建议。一般建议包括：) - 确保服务器运行环境的网络连接稳定且速度良好，特别是与 MiniMax API 主机的连接。 - 对于需要大量计算的工具（如视频生成），请耐心等待或使用异步查询机制。

资源限制

• 请注意 MiniMax API 可能存在的调用频率限制、并发限制或特定功能（如语音克隆、视频生成）的使用额度限制。
• 超出限制可能会导致 API 调用失败。
• 请参考 MiniMax 官方文档或平台说明了解具体的资源限制策略。