ultralytics-mcp 0.1.5 → 0.1.7

package/README.md

@@ -19,11 +19,9 @@ dataset uploads.
 - [Get API Key](#get-api-key)
 - [Environment Variables](#environment-variables)
 - [Installation](#installation)
-  - [Claude Code](#claude-code)
-  - [Codex](#codex)
 - [Verify Setup](#verify-setup)
 - [What You Can Do](#what-you-can-do)
-- [Tools](#tools-27)
+- [Tools](#tools)
 - [Safety](#safety)
 - [Troubleshooting](#troubleshooting)
 - [Development](#development)
@@ -61,7 +59,7 @@ Works in many MCP clients that accept JSON stdio server definitions.
   "mcpServers": {
     "ultralytics": {
       "command": "npx",
-      "args": ["-y", "ultralytics-mcp"],
+      "args": ["-y", "ultralytics-mcp@latest"],
       "env": {
         "ULTRALYTICS_API_KEY": "ul_your_api_key_here"
       }
@@ -70,12 +68,34 @@ Works in many MCP clients that accept JSON stdio server definitions.
 }
 ```
 
-### Claude Code
+<details>
+<summary>Antigravity</summary>
+
+Add via the Antigravity settings or by updating your configuration file:
+
+```json
+{
+  "mcpServers": {
+    "ultralytics": {
+      "command": "npx",
+      "args": ["-y", "ultralytics-mcp@latest"],
+      "env": {
+        "ULTRALYTICS_API_KEY": "ul_your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary>Claude Code</summary>
 
 Add server with Claude Code CLI:
 
 ```bash
-claude mcp add ultralytics --env ULTRALYTICS_API_KEY=ul_your_api_key_here -- npx -y ultralytics-mcp
+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`:
@@ -85,7 +105,7 @@ Or add a project-scoped server in repo-root `.mcp.json`:
   "mcpServers": {
     "ultralytics": {
       "command": "npx",
-      "args": ["-y", "ultralytics-mcp"],
+      "args": ["-y", "ultralytics-mcp@latest"],
       "env": {
         "ULTRALYTICS_API_KEY": "ul_your_api_key_here"
       }
@@ -94,12 +114,22 @@ Or add a project-scoped server in repo-root `.mcp.json`:
 }
 ```
 
-### Codex
+</details>
+
+<details>
+<summary>Claude Desktop</summary>
+
+Follow the MCP install [guide](https://modelcontextprotocol.io/quickstart/user), use the standard config above.
+
+</details>
+
+<details>
+<summary>Codex</summary>
 
 Add server with Codex CLI:
 
 ```bash
-codex mcp add ultralytics --env ULTRALYTICS_API_KEY=ul_your_api_key_here -- npx -y ultralytics-mcp
+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`:
@@ -107,12 +137,62 @@ Or add it directly to `~/.codex/config.toml`:
 ```toml
 [mcp_servers.ultralytics]
 command = "npx"
-args = ["-y", "ultralytics-mcp"]
+args = ["-y", "ultralytics-mcp@latest"]
 
 [mcp_servers.ultralytics.env]
 ULTRALYTICS_API_KEY = "ul_your_api_key_here"
 ```
 
+</details>
+
+<details>
+<summary>Cursor</summary>
+
+#### Click the button to install:
+
+[<img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Install in Cursor">](https://cursor.com/en/install-mcp?name=ultralytics&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInVsdHJhbHl0aWNzLW1jcEBsYXRlc3QiXSwiZW52Ijp7IlVMVFJBTFlUSUNTX0FQSV9LRVkiOiJ1bF95b3VyX2FwaV9rZXlfaGVyZSJ9fQ%3D%3D)
+
+> **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`.
+
+</details>
+
+<details>
+<summary>Gemini CLI</summary>
+
+Follow the MCP install [guide](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md#configure-the-mcp-server-in-settingsjson), use the standard config above.
+
+</details>
+
+<details>
+<summary>VS Code / Copilot</summary>
+
+#### Click the button to install:
+
+[<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF" alt="Install in VS Code">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522ultralytics%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522ultralytics-mcp%2540latest%2522%255D%252C%2522env%2522%253A%257B%2522ULTRALYTICS_API_KEY%2522%253A%2522ul_your_api_key_here%2522%257D%257D)
+
+> **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](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server), use the standard config above. You can also install the server using the VS Code CLI:
+
+```bash
+# 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.
+
+</details>
+
+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
@@ -141,65 +221,19 @@ You should see `ultralytics` in configured MCP servers.
 - 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](./TOOLS.md) for full parameter reference, safety notes, local-path behavior, and examples for tricky tools.
 
-## Tools (27)
-
-### Projects (5 tools)
-
-| Tool | Description |
-| --- | --- |
-| `projects_list` | List projects in your Ultralytics workspace |
-| `projects_get` | Get one project by id, slug, `username/slug`, or `ul://` |
-| `projects_create` | Create a new project |
-| `projects_delete` | Soft-delete a project |
-| `explore_projects` | Search public projects on Ultralytics Explore |
-
-### Datasets (12 tools)
-
-| Tool | Description |
-| --- | --- |
-| `datasets_list` | List datasets in your Ultralytics workspace |
-| `datasets_get` | Get one dataset by id, slug, `username/slug`, or `ul://` |
-| `datasets_create` | Create a new dataset |
-| `datasets_delete` | Soft-delete a dataset |
-| `dataset_images_list` | List images in a dataset with optional filters |
-| `dataset_ingest` | Start a remote ingest job from a source URL |
-| `dataset_upload_file` | Upload a local archive file for dataset ingest |
-| `dataset_upload_folder` | Upload a local image folder for dataset ingest |
-| `dataset_upload_video` | Upload a local video by extracting frames for dataset ingest |
-| `dataset_export` | Get an export link for latest or frozen dataset version |
-| `dataset_version_create` | Create a frozen dataset version snapshot |
-| `explore_datasets` | Search public datasets on Ultralytics Explore |
-
-### Models (4 tools)
-
-| Tool | Description |
-| --- | --- |
-| `models_list` | List trained models and summary metrics |
-| `models_get` | Get one model and its details |
-| `model_predict` | Run inference from an image URL or base64 input |
-| `model_download` | Download a model weight file to a local path |
-
-### Training (2 tools)
-
-| Tool | Description |
-| --- | --- |
-| `training_monitor` | Inspect status, progress, latest metrics, and optional history |
-| `training_start` | Start a cloud training job with explicit cost confirmation |
-
-### Exports (3 tools)
-
-| Tool | Description |
-| --- | --- |
-| `exports_list` | List export jobs |
-| `export_status` | Check export job status |
-| `export_create` | Create an export job with explicit cost confirmation |
-
-### Infrastructure (1 tool)
-
-| Tool | Description |
-| --- | --- |
-| `gpu_availability` | Check cloud GPU availability |
+- Projects: 5 tools
+- Datasets: 12 tools
+- Models: 4 tools
+- Training: 2 tools
+- Exports: 3 tools
+- Infrastructure: 1 tool
 
 ## Safety
 
@@ -207,6 +241,8 @@ You should see `ultralytics` in configured MCP servers.
 - `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
 
 ## Troubleshooting
 
@@ -231,7 +267,7 @@ characters after prefix.
 ### Manual server smoke test
 
 ```bash
-ULTRALYTICS_API_KEY=ul_your_api_key_here npx -y ultralytics-mcp
+ULTRALYTICS_API_KEY=ul_your_api_key_here npx -y ultralytics-mcp@latest
 ```
 
 If command exits immediately with config error, fix environment first.
@@ -243,4 +279,5 @@ npm install
 npm run check
 npm test
 npm run build
+npm run generate:tools
 ```