Ultralytics Platform MCP README

Ultralytics Platform MCP

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

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.

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"}}'

Verify

Run claude mcp list or codex mcp list. You should see ultralytics among the configured MCP servers.

Tools

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.

Platform API errors

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.