Ultralytics Platform MCP

Ultralytics Platform MCP

用于 Ultralytics Platform 工作流的 MCP 服务：项目、数据集、模型、训练、预测、导出和数据集上传。

重要

这是独立的社区项目，与 Ultralytics 无关联，也未获其认可。

安装 · 工具 · 安全 · 故障排查

试着这样提问

• “显示我的 Ultralytics 项目，以及哪些数据集已准备好用于训练。”
• “创建一个名为 traffic-cams 的私有项目，并将 ./clips/junction.mp4 上传为数据集。”
• “用 yolo11n 在 traffic-cams 上微调 50 个 epoch。”
• “训练进展如何？显示最近 10 个 epoch 的指标。”
• “用训练好的模型处理 https://example.com/frame.jpg，然后将权重下载到 ./weights。”
• “将我的 scratch 项目移至回收站。”（可在 30 天内恢复）

https://github.com/user-attachments/assets/449d051b-d162-4539-93c5-94be478303f0

安装

你需要：

• Node.js >=20
• Ultralytics Platform API 密钥
• ffmpeg 和 ffprobe，且位于 PATH 中，以便从本地视频文件上传数据集
• Claude Code、Codex 或其他能够启动 stdio 服务的 MCP 客户端

获取 API 密钥

登录 Ultralytics Platform，打开 Settings -> API Keys，然后创建或复制密钥。官方的 API 密钥文档介绍了 密钥的创建、使用和撤销方法。

环境变量

将 ULTRALYTICS_API_KEY 视为持有者令牌。仅通过 MCP 客户端的环境配置传递该密钥。切勿将真实密钥粘贴到提示词、脚本或已提交的配置文件中。本仓库会忽略项目级 .mcp.json 文件，以降低意外提交密钥的风险；如果密钥泄露，请在 Ultralytics Platform 中撤销并创建新密钥。

标准配置

适用于接受 JSON stdio 服务定义的 MCP 客户端。

{
  "mcpServers": {
    "ultralytics": {
      "command": "npx",
      "args": ["-y", "ultralytics-mcp@latest"],
      "env": {
        "ULTRALYTICS_API_KEY": "ul_your_api_key_here"
      }
    }
  }
}

这些示例使用最新发布的 npm 版本。升级后，请重启 MCP 客户端 或会话，以便新的服务进程加载最新的软件包。

claude mcp add ultralytics --env ULTRALYTICS_API_KEY=ul_your_api_key_here -- npx -y ultralytics-mcp@latest

{
  "mcpServers": {
    "ultralytics": {
      "command": "npx",
      "args": ["-y", "ultralytics-mcp@latest"],
      "env": {
        "ULTRALYTICS_API_KEY": "ul_your_api_key_here"
      }
    }
  }
}

codex mcp add ultralytics --env ULTRALYTICS_API_KEY=ul_your_api_key_here -- npx -y ultralytics-mcp@latest

[mcp_servers.ultralytics]
command = "npx"
args = ["-y", "ultralytics-mcp@latest"]

[mcp_servers.ultralytics.env]
ULTRALYTICS_API_KEY = "ul_your_api_key_here"

code --add-mcp '{"name":"ultralytics","command":"npx","args":["-y","ultralytics-mcp@latest"],"env":{"ULTRALYTICS_API_KEY":"ul_your_api_key_here"}}'

验证

运行 claude mcp list 或 codex mcp list。你应该会在已配置的 MCP 服务中看到 ultralytics。

工具

完整的参数参考、安全说明、本地路径行为以及棘手工具的示例，请参阅 TOOLS.md。

安全

• 项目和数据集默认设为私有，即使平台本身默认设为公开
• export_create 需要 confirm_cost: true
• training_start 需要 confirm_cost: true；如果在已有模型上重启训练，且该模型已有记录的运行记录，则还需要 confirm_history_loss: true。此操作会不可逆地替换模型状态、轮数和训练结果历史记录
• 启动训练任务或导出会立即产生费用，因此估算费用和剩余余额会在任务启动后报告，而非启动前
• 在检查点模式下使用 training_start（基准检查点，如 yolo11n.pt，而非现有模型引用）时，会先创建项目模型，再由平台检查检查点的任务是否与数据集的任务匹配
• 如果检查失败，已创建的模型不会自动删除。错误信息会指出模型；请检查模型，并在不需要时使用 models_delete 删除
• 取消正在运行的训练任务会保留最新检查点，并保留模型
• export_cancel 只有在检测到导出状态为 queued、starting 或 running 时才会继续；对于其他所有状态（包括无法识别的状态）都会拒绝操作。由于状态检查和取消请求并非原子操作，如果导出在两者之间完成，其产物可能会被不可逆地删除
• 删除项目或数据集会将其软删除至回收站，并可在 30 天内恢复。删除项目时会报告级联删除数量；删除数据集时，其图像和标注也会一并移入回收站，而基于该数据集训练的模型不受影响
• 如果项目或数据集引用不明确，操作会失败，而不会猜测
• 未声明的工具参数会导致失败，而不会被静默忽略
• 签名上传和下载 URL 不会转发 Authorization
• 本地上传工具、使用 file_path 的 model_predict，以及 deployment_predict 都会从 MCP 客户端主机读取文件；仅批准那些你预期要分享给 Ultralytics 的路径
• model_download 会将文件写入指定的本地路径；批准前请检查 output_path 和 overwrite
• 将带有 data.yaml 类别名称的命名 YOLO ZIP 添加到现有数据集时，会导入其标签并合并类别
• 重新导入不会重新标注数据集中已有的图像（请使用标注编辑器）；在不同数据集划分中重新上传同一图像可能会产生重复项

故障排除

API 密钥无效

ULTRALYTICS_API_KEY 必须以 ul_ 开头，且前缀后恰好包含 40 个十六进制字符。

服务未加载

运行 claude mcp list 或 codex mcp list，然后确认已安装 npx 和 Node.js，并确认 ULTRALYTICS_API_KEY 已传递给客户端——添加服务时通过 --env 传入，或在 ~/.codex/config.toml 中设置。在 Claude Code 中，运行 claude mcp get ultralytics 可查看解析后的配置。

要单独对服务进行冒烟测试：

ULTRALYTICS_API_KEY=ul_your_api_key_here npx -y ultralytics-mcp@latest

如果命令因配置错误立即退出，请先修复环境配置。

平台 API 错误

对于身份验证、速率限制或端点行为，请对照官方 Ultralytics Platform REST API 文档。 寻求帮助时，请提供工具名称、请求摘要、响应状态、已脱敏的响应正文，以及最小复现示例。请勿提供真实 API 密钥、签名 URL、私有数据集内容或私有模型产物。

贡献

有关设置、检查套件和实时冒烟测试，请参阅 CONTRIBUTING.md。