
MCP server for Ultralytics Platform
workflows: projects, datasets, models, training, prediction, exports, and
dataset uploads.
IMPORTANT
Independent community project. Not affiliated with or endorsed by Ultralytics.
Install · Tools · Safety · Troubleshooting
Try Asking
- "Show me my Ultralytics projects and which datasets are ready to train on."
- "Create a private project called
traffic-cams and upload ./clips/junction.mp4 as a dataset."
- "Fine-tune
yolo11n on traffic-cams for 50 epochs."
- "How is that training going? Show me the last 10 epochs of metrics."
- "Run the trained model on
https://example.com/frame.jpg, then download the weights to ./weights."
- "Move my
scratch project to trash." (restorable for 30 days)
https://github.com/user-attachments/assets/449d051b-d162-4539-93c5-94be478303f0
Installation
You need:
- Node.js
>=20
- An Ultralytics Platform API key
ffmpeg and ffprobe on PATH, to upload a dataset from a local video file
- Claude Code, Codex, or another MCP client that can launch stdio servers
Get an API key
Sign in at Ultralytics Platform, open
Settings -> API Keys, and create or copy a key. The official
API key docs cover
creation, usage, and revocation.
Environment variables
| Variable | Required | Description |
|---|
ULTRALYTICS_API_KEY | ✅ | Ultralytics API key. Expected format: ul_ followed by 40 hex characters |
ULTRALYTICS_API_BASE | ❌ | Advanced: override API base URL. Default: https://platform.ultralytics.com/api |
Treat ULTRALYTICS_API_KEY as a bearer token. Pass it through your MCP client's
environment configuration only. Never paste real keys into prompts, scripts, or
committed config files. Project-scoped .mcp.json files are ignored by this repo
to reduce accidental key commits; if a key is exposed, revoke it in Ultralytics
Platform and create a replacement.
Standard config
Works in MCP clients that accept JSON stdio server definitions.
{
"mcpServers": {
"ultralytics": {
"command": "npx",
"args": ["-y", "ultralytics-mcp@latest"],
"env": {
"ULTRALYTICS_API_KEY": "ul_your_api_key_here"
}
}
}
}
These examples track the latest published npm release. Restart your MCP client
or session after upgrading, so the new server process picks up the latest
package.
Antigravity
Add the standard config above through Antigravity settings, or by editing your
configuration file directly.
Claude Code
claude mcp add ultralytics --env ULTRALYTICS_API_KEY=ul_your_api_key_here -- npx -y ultralytics-mcp@latest
Or add a project-scoped server in repo-root .mcp.json:
{
"mcpServers": {
"ultralytics": {
"command": "npx",
"args": ["-y", "ultralytics-mcp@latest"],
"env": {
"ULTRALYTICS_API_KEY": "ul_your_api_key_here"
}
}
}
}
Claude Desktop
Follow the MCP install guide
with the standard config above.
Codex
codex mcp add ultralytics --env ULTRALYTICS_API_KEY=ul_your_api_key_here -- npx -y ultralytics-mcp@latest
Or add it directly to ~/.codex/config.toml:
[mcp_servers.ultralytics]
command = "npx"
args = ["-y", "ultralytics-mcp@latest"]
[mcp_servers.ultralytics.env]
ULTRALYTICS_API_KEY = "ul_your_api_key_here"
Cursor

Important
The install button writes a placeholder key. After installing, open your Cursor MCP config and replace ul_your_api_key_here with your Ultralytics API key, then restart Cursor.
To install manually, go to Cursor Settings -> MCP -> Add new MCP Server
(or edit ~/.cursor/mcp.json) and use the standard config above.
Gemini CLI
Follow the MCP install guide
with the standard config above.
VS Code / Copilot

Important
The install button writes a placeholder key. After installing, open your VS Code MCP config and replace ul_your_api_key_here with your Ultralytics API key, then restart VS Code.
To install manually, follow the MCP install
guide,
or use the VS Code CLI:
code --add-mcp '{"name":"ultralytics","command":"npx","args":["-y","ultralytics-mcp@latest"],"env":{"ULTRALYTICS_API_KEY":"ul_your_api_key_here"}}'
Verify
Run claude mcp list or codex mcp list. You should see ultralytics among
the configured MCP servers.
See TOOLS.md for the full parameter reference, safety notes,
local-path behavior, and examples for the tricky tools.
Safety
- Projects and datasets are created private by default, even though the platform itself defaults to public
export_create requires confirm_cost: true
training_start requires confirm_cost: true, plus confirm_history_loss: true when restarting training on an existing model that already has a recorded run. That path replaces its status, epoch count, and training result history irrecoverably
- Starting a training job or an export is billable immediately, so the estimated cost and remaining balance are reported after the job starts, not before
training_start in checkpoint mode (a base checkpoint like yolo11n.pt, not an existing model ref) creates the project model before the platform checks the checkpoint's task against the dataset's
- If that check fails, the model it already created is not deleted automatically. The error names the model; review it and delete it with
models_delete if it is unwanted
- Cancelling a running training job preserves the latest checkpoint and keeps the model
export_cancel proceeds only when it observes an export as queued, starting, or running, and refuses every other status, including unrecognized ones. Because the status check and the cancel request are not atomic, an export that finishes between them may have its artifact irreversibly deleted
- Deleting a project or dataset is a soft delete to trash, restorable for 30 days. Deleting a project reports the cascade count; deleting a dataset moves its images and annotations with it and leaves models trained on it unaffected
- Ambiguous project or dataset refs fail instead of guessing
- Undeclared tool arguments fail instead of being silently ignored
- Signed upload and download URLs do not forward
Authorization
- Local upload tools,
model_predict with file_path, and deployment_predict read files from the MCP client host; approve calls only for paths you expect to share with Ultralytics
model_download writes to the requested local path; review output_path and overwrite before approving
- Adding a named YOLO ZIP (with
data.yaml class names) to an existing dataset imports its labels and merges classes
- Re-ingest does not re-label images already in the dataset (use the annotation editor); re-uploading the same image under a different split can create a duplicate
Troubleshooting
Invalid API key
ULTRALYTICS_API_KEY must start with ul_ and contain exactly 40 hex
characters after the prefix.
Server not loading
Run claude mcp list or codex mcp list, then verify that npx and Node.js
are installed and that ULTRALYTICS_API_KEY reached the client — passed with
--env when adding the server, or set in ~/.codex/config.toml. In Claude
Code, claude mcp get ultralytics shows the resolved config.
To smoke-test the server on its own:
ULTRALYTICS_API_KEY=ul_your_api_key_here npx -y ultralytics-mcp@latest
If the command exits immediately with a config error, fix the environment
first.
For authentication, rate-limit, or endpoint behavior, compare against the
official Ultralytics Platform REST API docs.
When asking for help, include the tool name, request summary, response status,
redacted response body, and a minimal reproduction. Do not include real API
keys, signed URLs, private dataset contents, or private model artifacts.
Contributing
See CONTRIBUTING.md for setup, the check suite, and the
live smoke test.