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.

Demo

https://github.com/user-attachments/assets/cc927af9-0211-41f1-9054-eb9c74578f34

Table of Contents

• Requirements
• Get API Key
• Environment Variables
• Installation
• Verify Setup
• What You Can Do
• Tools
• Safety
• Troubleshooting
• Development

Requirements

• Node.js >=20
• 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 API Key

1. Sign in at Ultralytics Platform.
2. Open Settings -> API Keys.
3. Create or copy an API key.

See the official Ultralytics API key docs for key creation, usage, and revocation details.

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.

Installation

Standard Config

Works in many 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"
      }
    }
  }
}

Add via the Antigravity settings or by updating your configuration file:

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

Add server with Claude Code CLI:

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

Follow the MCP install guide, use the standard config above.

Add server with Codex CLI:

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"

Click the button to install:

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.

Or install manually:

Go to Cursor Settings -> MCP -> Add new MCP Server (or edit ~/.cursor/mcp.json directly) and use the standard config above: command set to npx, args set to ["-y", "ultralytics-mcp@latest"], and ULTRALYTICS_API_KEY in env.

Follow the MCP install guide, use the standard config above.

Click the button to install:

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.

Or install manually:

Follow the MCP install guide, use the standard config above. You can also install the server using the VS Code CLI:

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

After installation, the Ultralytics MCP server will be available for use with your GitHub Copilot agent in VS Code.

These examples track latest published npm release. Restart MCP client or session after upgrading so new server process picks up latest package.

Verify Setup

Claude Code

claude mcp list

You should see ultralytics in configured MCP servers.

Codex

codex mcp list

You should see ultralytics in configured MCP servers.

What You Can Do

• Browse projects, datasets, models, exports, GPU availability
• Resolve project and dataset refs by id, slug, username/slug, or ul://
• Search public projects and datasets on Ultralytics Explore
• Start dataset ingest jobs and upload archive files, folders, or videos
• Monitor training progress and inspect latest metrics or recent metric history
• Run model prediction from image URL or base64 input
• Download model weights to local path
• Create exports and training jobs with explicit cost confirmation
• Pass advanced YOLO training settings through training_start.train_args
• Start training from existing project models or official YOLO base checkpoints

Tools

See TOOLS.md for full parameter reference, safety notes, local-path behavior, and examples for tricky tools.

• Projects: 5 tools
• Datasets: 12 tools
• Models: 5 tools
• Training: 2 tools
• Exports: 3 tools
• Infrastructure: 1 tool

Safety

• ULTRALYTICS_API_KEY is a bearer token; pass it via MCP client env and never commit real keys
• export_create requires confirm_cost: true
• training_start requires confirm_cost: true
• Ambiguous project or dataset refs fail instead of guessing
• Signed upload and download URLs do not forward Authorization
• Local upload tools 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
• Re-uploading labeled copies may duplicate dataset image records instead of attaching labels to existing images
• Images-only dataset uploads may be inferred as classify; include labels when task preservation matters

Troubleshooting

Invalid API key

ULTRALYTICS_API_KEY must start with ul_ and contain exactly 40 hex characters after prefix.

Server not loading in Claude Code

• run claude mcp list
• verify npx and Node.js are installed
• verify ULTRALYTICS_API_KEY was passed with --env when adding server
• if needed, inspect server config with claude mcp get ultralytics

Server not loading in Codex

• run codex mcp list
• verify npx and Node.js are installed
• verify ULTRALYTICS_API_KEY value in ~/.codex/config.toml or codex mcp add command

Manual server smoke test

ULTRALYTICS_API_KEY=ul_your_api_key_here npx -y ultralytics-mcp@latest

If command exits immediately with config error, fix 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.

Development

npm install
npm run check
npm test
npm run build
npm run generate:tools