Ultralytics Platform MCP

Ultralytics Platform MCP

Ultralytics Platformのワークフローに対応するMCP サーバーです。プロジェクト、データセット、モデル、トレーニング、予測、エクスポート、データセットのアップロードを利用できます。

重要

独立したコミュニティプロジェクトです。Ultralyticsとは提携しておらず、Ultralyticsの推奨を受けたものでもありません。

インストール · ツール · 安全性 · トラブルシューティング

こんなことを聞いてみましょう

• 「Ultralyticsのプロジェクトと、トレーニングに使える状態のデータセットを教えてください。」
• 「traffic-camsという名前の非公開プロジェクトを作成して、./clips/junction.mp4をデータセットとしてアップロードしてください。」
• 「traffic-camsでyolo11nを50エポックファインチューニングしてください。」
• 「トレーニングの進捗はどうですか？直近10エポックの指標を表示してください。」
• 「トレーニング済みモデルをhttps://example.com/frame.jpgに対して実行してから、重みを./weightsにダウンロードしてください。」
• 「scratchプロジェクトをごみ箱に移動してください。」（30日間は復元できます）

https://github.com/user-attachments/assets/449d051b-d162-4539-93c5-94be478303f0

インストール

必要なもの：

• Node.js >=20
• Ultralytics Platform APIキー
• ローカルの動画ファイルからデータセットをアップロードする場合は、PATH上のffmpegとffprobe
• Claude Code、Codex、またはstdioサーバーを起動できるその他のMCPクライアント

APIキーの取得

Ultralytics Platformにサインインし、Settings -> API Keysを開いて、キーを作成またはコピーします。公式のAPIキーのドキュメントでは、作成、使用、失効について説明しています。

環境変数

ULTRALYTICS_API_KEYはベアラートークンとして扱ってください。MCPクライアントの環境設定を通じてのみ渡してください。実際のキーをプロンプト、スクリプト、コミット対象の設定ファイルに貼り付けないでください。キーが誤ってコミットされるのを防ぐため、このリポジトリではプロジェクトスコープの.mcp.jsonファイルを無視します。キーが漏えいした場合は、Ultralytics Platformでそのキーを失効させ、新しいキーを作成してください。

標準設定

JSON stdio サーバー定義を受け付ける MCP クライアントで動作します。

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

これらの例では、公開されている最新の npm リリースを使用しています。アップグレード後は、MCP クライアントまたはセッションを再起動して、新しいサーバープロセスで最新のパッケージが読み込まれるようにしてください。

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

確認

claude mcp list または codex mcp list を実行してください。設定済みの MCP サーバーの中に ultralytics が表示されます。

ツール

パラメーターの詳細、安全上の注意、ローカルパスの動作、扱いが難しいツールの使用例については、TOOLS.md を参照してください。

安全性

• プロジェクトとデータセットは、プラットフォーム自体のデフォルト設定が公開であっても、デフォルトで非公開として作成されます
• export_create には confirm_cost: true が必要です
• training_start には confirm_cost: true が必要です。また、記録済みの実行履歴がある既存モデルでトレーニングを再開する場合は、confirm_history_loss: true も必要です。この場合、ステータス、エポック数、トレーニング結果の履歴が置き換えられ、復元できなくなります
• トレーニングジョブまたはエクスポートを開始すると、直ちに課金されます。そのため、推定コストと残高はジョブの開始後に報告されます
• チェックポイントモードの training_start（既存モデルの参照ではなく、yolo11n.pt などのベースチェックポイントを使用する場合）は、プラットフォームがチェックポイントのタスクとデータセットのタスクを照合する前に、プロジェクトモデルを作成します
• 照合に失敗しても、すでに作成されたモデルは自動的に削除されません。エラーにモデル名が表示されるので、内容を確認し、不要であれば models_delete で削除してください
• 実行中のトレーニングジョブをキャンセルしても、最新のチェックポイントは保持され、モデルも残ります
• export_cancel は、エクスポートのステータスが queued、starting、または running であることを確認した場合にのみ処理を進めます。認識できないステータスを含め、それ以外のすべてのステータスでは拒否します。ステータス確認とキャンセル要求はアトミックではないため、その間にエクスポートが完了すると、アーティファクトが復元できない形で削除される可能性があります
• プロジェクトまたはデータセットの削除は、ゴミ箱へのソフト削除であり、30 日間は復元できます。プロジェクトを削除するとカスケード削除の件数が報告されます。データセットを削除すると、画像とアノテーションも一緒に移動しますが、そのデータセットでトレーニングしたモデルには影響しません
• 参照先のプロジェクトまたはデータセットを特定できない場合、推測せずにエラーになります
• 宣言されていないツール引数は、黙って無視されず、エラーになります
• 署名付きのアップロード URL とダウンロード URL では、Authorization は転送されません
• ローカルアップロードツール、file_path を指定した model_predict、および deployment_predict は、MCP クライアントのホストからファイルを読み取ります。Ultralytics との共有を想定したパスに対する呼び出しのみ承認してください
• model_download は指定されたローカルパスに書き込みます。承認前に output_path と overwrite を確認してください
• 名前付き YOLO ZIP（クラス名を含む data.yaml があるもの）を既存のデータセットに追加すると、ラベルがインポートされ、クラスが統合されます
• 再取り込みでは、データセットにすでに含まれている画像にラベルは付け直されません（アノテーションエディターを使用してください）。同じ画像を別の分割先に再アップロードすると、重複が作成される可能性があります

トラブルシューティング

API キーが無効

ULTRALYTICS_API_KEY は ul_ で始まり、接頭辞の後に 40 文字ちょうどの 16 進数文字列が続く必要があります。

サーバーが読み込まれない

claude mcp list または codex mcp list を実行し、npx と Node.js がインストールされていること、また ULTRALYTICS_API_KEY がクライアントに渡されていることを確認してください。サーバーの追加時に --env で渡すか、~/.codex/config.toml に設定します。Claude Code では、claude mcp get ultralytics を実行すると、解決済みの設定を確認できます。

サーバー単体で簡単な動作確認を行うには、次を実行します。

ULTRALYTICS_API_KEY=ul_your_api_key_here npx -y ultralytics-mcp@latest

コマンドが設定エラーですぐに終了する場合は、まず環境を修正してください。

プラットフォーム API エラー

認証、レート制限、またはエンドポイントの動作については、公式の Ultralytics Platform REST API ドキュメントと照合してください。サポートを依頼する際は、ツール名、リクエストの概要、レスポンスのステータス、機密情報を伏せたレスポンス本文、および最小限の再現手順を記載してください。実際の API キー、署名付き URL、非公開のデータセット内容、非公開のモデルアーティファクトは記載しないでください。

貢献

セットアップ、チェック一式、ライブ動作確認については、CONTRIBUTING.md を参照してください。