内容
# Ultralytics 平台 MCP
[](https://www.npmjs.com/package/ultralytics-mcp)
[](https://github.com/amanharshx/ultralytics-mcp/actions/workflows/ci.yml)
[](./LICENSE)
适用于 [Ultralytics 平台](https://platform.ultralytics.com) 的 MCP 服务器，支持工作流：项目、数据集、模型、训练、预测、导出和数据集上传。
> [!IMPORTANT]
> 独立的社区项目，与 Ultralytics 无关，也未得到 Ultralytics 的认可。
---
## 目录
- [要求](#要求)
- [获取 API 密钥](#获取-api-密钥)
- [环境变量](#环境变量)
- [安装](#安装)
- [Claude 代码](#claude-代码)
- [Codex](#codex)
- [验证设置](#验证设置)
- [您可以执行的操作](#您可以执行的操作)
- [工具](#工具-27)
- [安全性](#安全性)
- [故障排除](#故障排除)
- [开发](#开发)
---
## 要求
- Node.js `>=20`
- Ultralytics 平台 API 密钥
- `ffmpeg` 和 `ffprobe` 在 `PATH` 中，以便从本地视频文件上传数据集
- Claude 代码、Codex 或另一个可以启动_stdio 服务器的 MCP 客户端
## 获取 API 密钥
1. 在 [Ultralytics 平台](https://platform.ultralytics.com) 登录。
2. 打开 `设置 -> API 密钥`。
3. 创建或复制 API 密钥。
## 环境变量
| 变量 | 必需 | 描述 |
| --- | --- | --- |
| `ULTRALYTICS_API_KEY` | ✅ | Ultralytics API 密钥。预期格式：`ul_` 后跟 40 个十六进制字符 |
| `ULTRALYTICS_API_BASE` | ❌ | 高级：覆盖 API 基本 URL。默认值：`https://platform.ultralytics.com/api` |
## 安装
### 标准配置
适用于许多接受 JSON stdio 服务器定义的 MCP 客户端。
```json
{
"mcpServers": {
"ultralytics": {
"command": "npx",
"args": ["-y", "ultralytics-mcp"],
"env": {
"ULTRALYTICS_API_KEY": "ul_您的_api_密钥_在此"
}
}
}
}
```
### Claude 代码
使用 Claude 代码 CLI 添加服务器：
```bash
claude mcp add ultralytics --env ULTRALYTICS_API_KEY=ul_您的_api_密钥_在此 -- npx -y ultralytics-mcp
```
或在仓库根目录的 `.mcp.json` 中添加项目范围的服务器：
```json
{
"mcpServers": {
"ultralytics": {
"command": "npx",
"args": ["-y", "ultralytics-mcp"],
"env": {
"ULTRALYTICS_API_KEY": "ul_您的_api_密钥_在此"
}
}
}
}
```
### Codex
使用 Codex CLI 添加服务器：
```bash
codex mcp add ultralytics --env ULTRALYTICS_API_KEY=ul_您的_api_密钥_在此 -- npx -y ultralytics-mcp
```
或直接添加到 `~/.codex/config.toml`：
```toml
[mcp_servers.ultralytics]
command = "npx"
args = ["-y", "ultralytics-mcp"]
[mcp_servers.ultralytics.env]
ULTRALYTICS_API_KEY = "ul_您的_api_密钥_在此"
```
## 验证设置
### Claude 代码
```bash
claude mcp list
```
您应该在配置的 MCP 服务器中看到 `ultralytics`。
### Codex
```bash
codex mcp list
```
您应该在配置的 MCP 服务器中看到 `ultralytics`。
## 您可以执行的操作
- 浏览项目、数据集、模型、导出、GPU 可用性
- 通过 ID、slug、 `username/slug` 或 `ul://` 解析项目和数据集引用
- 在 Ultralytics Explore 上搜索公共项目和数据集
- 启动数据集摄取作业并上传存档文件、文件夹或视频
- 监控训练进度并检查最新指标或最近的指标历史
- 从图像 URL 或 base64 输入运行模型预测
- 下载模型权重到本地路径
- 创建导出和训练作业，确认明确成本
- 通过 `training_start.train_args` 传递高级 YOLO 训练设置
- 从现有项目模型或官方 YOLO 基础检查点开始训练
## 工具（27）
### 项目（5 个工具）
| 工具 | 描述 |
| --- | --- |
| `projects_list` | 列出 Ultralytics 工作空间中的项目 |
| `projects_get` | 通过 ID、slug、 `username/slug` 或 `ul://` 获取一个项目 |
| `projects_create` | 创建一个新项目 |
| `projects_delete` | 软删除一个项目 |
| `explore_projects` | 在 Ultralytics Explore 上搜索公共项目 |
### 数据集（12 个工具）
| 工具 | 描述 |
| --- | --- |
| `datasets_list` | 列出 Ultralytics 工作空间中的数据集 |
| `datasets_get` | 通过 ID、slug、 `username/slug` 或 `ul://` 获取一个数据集 |
| `datasets_create` | 创建一个新数据集 |
| `datasets_delete` | 软删除一个数据集 |
| `dataset_images_list` | 列出数据集中的图像，可选过滤器 |
| `dataset_ingest` | 从源 URL 启动远程摄取作业 |
| `dataset_upload_file` | 上传本地存档文件进行数据集摄取 |
| `dataset_upload_folder` | 上传本地图像文件夹进行数据集摄取 |
| `dataset_upload_video` | 上传本地视频，通过提取帧进行数据集摄取 |
| `dataset_export` | 获取最新或冻结数据集版本的导出链接 |
| `dataset_version_create` | 创建冻结数据集版本快照 |
| `explore_datasets` | 在 Ultralytics Explore 上搜索公共数据集 |
### 模型（4 个工具）
| 工具 | 描述 |
| --- | --- |
| `models_list` | 列出训练好的模型和摘要指标 |
| `models_get` | 获取一个模型及其详细信息 |
| `model_predict` | 从图像 URL 或 base64 输入运行推理 |
| `model_download` | 下载模型权重文件到本地路径 |
### 训练（2 个工具）
| 工具 | 描述 |
| --- | --- |
| `training_monitor` | 检查状态、进度、最新指标和可选历史记录 |
| `training_start` | 从现有模型或官方 YOLO 基础检查点启动云训练作业，确认明确成本和可选 `train_args` 传递 |
### 导出（3 个工具）
| 工具 | 描述 |
| --- | --- |
| `exports_list` | 列出导出作业 |
| `export_status` | 检查导出作业状态 |
| `export_create` | 创建导出作业，确认明确成本 |
### 基础设施（1 个工具）
| 工具 | 描述 |
| --- | --- |
| `gpu_availability` | 检查云 GPU 可用性 |
## 安全性
- `export_create` 需要 `confirm_cost: true`
- `training_start` 需要 `confirm_cost: true`
- 不明确的项目或数据集引用失败，而不是猜测
- 签名的上传和下载 URL 不会转发 `Authorization`
## 故障排除
### 无效 API 密钥
`ULTRALYTICS_API_KEY` 必须以 `ul_` 开头，并包含前缀后 exactly 40 个十六进制字符。
### Claude 代码中服务器未加载
- 运行 `claude mcp list`
- 验证 `npx` 和 Node.js 已安装
- 验证 `ULTRALYTICS_API_KEY` 在添加服务器时是否使用 `--env` 传递
- 如有必要，使用 `claude mcp get ultralytics` 检查服务器配置
### Codex 中服务器未加载
- 运行 `codex mcp list`
- 验证 `npx` 和 Node.js 已安装
- 验证 `ULTRALYTICS_API_KEY` 值在 `~/.codex/config.toml` 或 `codex mcp add` 命令中
### 手动服务器烟雾测试
```bash
ULTRALYTICS_API_KEY=ul_您的_api_密钥_在此 npx -y ultralytics-mcp
```
如果命令立即退出并出现配置错误，请首先修复环境。
## 开发
```bash
npm install
npm run check
npm test
npm run build
```
