dokploy-api-mcp

Dokploy のデプロイ

セルフホスト可能な Dokploy インスタンス（v0.28 以降、v0.29.x までテスト済み）で、アプリケーションをデプロイして管理します。 Dokploy は、Docker と Traefik v3 を使用するオープンソースの PaaS（Vercel／Heroku の代替）です。

DOKPLOY_URL の末尾に /api を付けてはいけません。 MCP サーバーが自動的に /api を追加するため、ベース URL の末尾が /api の場合、すべてのリクエストが /api/api/... に送信され、すべての呼び出しが失敗します。 https://dokploy.example.com を使用してください。

クイックリファレンス

項目	値
ダッシュボード	https://<DOKPLOY_HOST>/
API ベース	https://<DOKPLOY_HOST>/api/
Swagger UI	https://<DOKPLOY_HOST>/swagger（ブラウザーでのログインが必要）
認証ヘッダー	x-api-key: <TOKEN>
CLI のインストール	npm install -g @dokploy/cli
MCP サーバー	@sattva/dokploy-mcp（API 全体をカバー。Dokploy v0.29.x で約 540 個のツール）
API バージョン	OpenAPI 3.1.0。ツール数は Dokploy のバージョンに応じます（v0.28.4 で 449 個、v0.29.8 で 539 個）
ドキュメント	https://docs.dokploy.com

初回実行 — セットアップ

初回使用時は、Dokploy MCP サーバーが設定されているか確認してください。設定されていない場合は、対話形式のセットアップを実行します。

1. Check: is a "dokploy" MCP server configured? (`claude mcp list`)
2. If NO → run: python3 skills/dokploy-api-mcp/scripts/setup.py
   (or the full path in the user's skill installation directory)
3. The script will:
   - Ask for the Dokploy URL (e.g., https://dokploy.example.com — without /api)
   - Ask for the API key (Dashboard → Settings → Profile → API/CLI)
   - Validate the connection and report how many endpoints the instance exposes
   - Ask which tool surface to use (tools / gateway / both)
   - Register the server via `claude mcp add-json`, or print the JSON to paste
     manually if the CLI is unavailable
4. Tell the user: "Restart Claude Code to activate the Dokploy MCP server."

CLI 引数を使う場合（非対話形式）：

python3 skills/dokploy-api-mcp/scripts/setup.py --url https://dokploy.example.com --key YOUR_API_KEY --mode gateway

--insecure は、自己署名証明書を使用するインスタンスに限って追加してください。TLS 検証が無効になり、API キーが検証されていない接続で送信されます。

セットアップ後、MCP サーバー（@sattva/dokploy-mcp、約 540 個のツール）は、次回の Claude Code の再起動後に利用できるようになります。すべての操作で curl より MCP ツールを優先してください。

環境変数

このスキルを使用する前に、次の環境変数を利用できることを確認してください。

DOKPLOY_URL=https://dokploy.example.com
DOKPLOY_API_KEY=<generated-api-token>

API トークンを生成するには、ダッシュボードで「Settings → Profile → API/CLI → Generate」の順に選択します。

デプロイのワークフロー

ステップ 1：現在の状態を確認する

# Get application status
curl -s -X GET "${DOKPLOY_URL}/api/trpc/application.one?input=$(python3 -c "
import urllib.parse, json
print(urllib.parse.quote(json.dumps({'json':{'applicationId':'APP_ID'}})))
")" -H "x-api-key: ${DOKPLOY_API_KEY}"

ステップ 2：デプロイを開始する

# Deploy application (POST — mutation)
curl -s -X POST "${DOKPLOY_URL}/api/application.deploy" \
  -H "x-api-key: ${DOKPLOY_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"json":{"applicationId":"APP_ID"}}'

ステップ 3：デプロイの状態を監視する

# Poll deployment status
curl -s -X GET "${DOKPLOY_URL}/api/trpc/deployment.all?input=$(python3 -c "
import urllib.parse, json
print(urllib.parse.quote(json.dumps({'json':{'applicationId':'APP_ID'}})))
")" -H "x-api-key: ${DOKPLOY_API_KEY}"

ステップ 4：正常性を確認する

curl -sk "https://<app-domain>/api/health"

API リファレンス

Dokploy は内部で tRPC を使用します。リクエスト形式は 2 種類あります。

クエリ（読み取り）— エンコードされた入力を指定する GET

GET /api/trpc/<router>.<procedure>?input=URL_ENCODED({"json":{...}})
Header: x-api-key: <token>

ミューテーション（書き込み）— JSON ボディを指定する POST

POST /api/<router>.<procedure>
Header: x-api-key: <token>
Header: Content-Type: application/json
Body: {"json":{...}}

主なエンドポイント

一覧は references/API-REFERENCE.md を参照してください（v0.28.4 の基準です。インスタンスで実際に使用できるエンドポイントは settings.getOpenApiDocument を実行して確認してください）。

エンドポイント	メソッド	用途
project.all	GET	すべてのプロジェクトを一覧表示
project.one	GET	ID でプロジェクトを取得
application.one	GET	アプリの詳細と状態を取得
application.deploy	POST	デプロイを開始
application.stop	POST	アプリケーションを停止
application.start	POST	アプリケーションを開始
application.update	POST	アプリの設定を更新
application.saveBuildType	POST	ビルドタイプを変更
application.saveEnvironment	POST	環境変数を設定
compose.one	GET	Compose サービスを取得
compose.deploy	POST	Compose サービスをデプロイ
deployment.all	GET	アプリのデプロイを一覧表示
domain.byApplicationId	GET	アプリのドメインを取得
domain.create	POST	カスタムドメインを追加
postgres.one	GET	PostgreSQL サービスを取得
redis.one	GET	Redis サービスを取得
mariadb.one	GET	MariaDB サービスを取得
mongo.one	GET	MongoDB サービスを取得
environment.byProjectId	GET	環境を一覧表示
rollback.rollback	POST	デプロイをロールバック
schedule.create	POST	スケジュール済みタスクを作成
backup.create	POST	バックアップ設定を作成
notification.createTelegram	POST	Telegram 通知を設定
docker.getContainersByAppNameMatch	GET	Docker コンテナーを一覧表示
application.readTraefikConfig	GET	Traefik の設定を読み取る

CLI の使用方法

# Install
npm install -g @dokploy/cli

# Authenticate (creates ~/.config/dokploy/config.json)
dokploy authenticate

# Verify token
dokploy verify

# Application management
dokploy app create   # Create new application
dokploy app deploy   # Deploy application
dokploy app stop     # Stop application
dokploy app delete   # Delete application

# Database management
dokploy db create    # Create database service
dokploy db delete    # Delete database service

# Environment variables
dokploy env set      # Set env vars
dokploy env list     # List env vars

# Project management
dokploy project create
dokploy project list

MCP サーバー（API 全体をカバー、約 540 個のツール）

MCP が利用できる場合は、必ず curl より MCP ツールを優先してください。 MCP は tRPC の URL エンコードとレスポンスの解析を自動的に処理します。

ツールの詳細は references/MCP-TOOLS.md を参照してください。

サーバーの動作（v1.1.0+）

• 安全性の注釈：GET ツールには readOnlyHint が付き、変更を加える動詞（deploy/delete/stop/update/...）には destructiveHint が付きます。クライアントは危険な呼び出しを強調表示したり、制限したりできます。
• レスポンスはコンパクトな JSON で、DOKPLOY_MAX_RESPONSE_CHARS（デフォルトは 50000）を超えると切り詰められ、_truncated マーカーが付加されます。むやみに上限を引き上げるのではなく、クエリを絞り込んでください。
• リクエストは DOKPLOY_TIMEOUT_MS（デフォルトは 30s）経過後にタイムアウトします。GET は 5xx/429 の場合に再試行されます。
• OpenAPI 仕様は OS の一時ディレクトリにキャッシュされます。そのため、Dokploy に一時的に接続できない場合でもサーバーは動作します。

ゲートウェイモード（v1.2.0+）— 540 個ではなく 4 個のツール

サーバーの env で DOKPLOY_MODE=gateway を設定すると、エンドポイントごとのツールが次の 4 つに置き換わります。

ツール	用途
dokploy_search(query)	キーワードでエンドポイントを検索
dokploy_describe(endpoint)	1 つのエンドポイントのパラメータスキーマを取得
dokploy_call(endpoint, params)	読み取り専用（GET）エンドポイントを呼び出す
dokploy_mutate(endpoint, params)	書き込みエンドポイントを呼び出す — 破壊的操作

フロー：検索 → 説明 → 呼び出し／変更。測定されたコストは、tools/list が 239 KB から 2.7 KB に減少（−98.9%）し、検出から呼び出しまでの一連の処理で約 0.8k トークンです。各ツールは、リクエストを送信する前に種類の異なるエンドポイントを拒否するため、読み取りと書き込みの区別が維持されます。このため、汎用の call 1 つではなく、4 つのツールが用意されています。

幅広く調査する場合はゲートウェイモードを使用してください。同じ少数のエンドポイントを毎回使う場合は、tools モード（デフォルト）または DOKPLOY_TOOLS プロファイルを使用してください。DOKPLOY_MODE=both を設定すると、両方のインターフェースが利用できます。

推奨：ツールセットを絞り込む

全ツールの一覧には約 540 個のツール（tools/list で約 60k トークン）が含まれます。日常的なデプロイには、env ブロックでプロファイルを設定してください。

"DOKPLOY_TOOLS": "project_*,application_*,compose_*,deployment_*,docker_*,domain_*,postgres_*,redis_*,backup_*,rollback_*,schedule_*,settings_health"

これによりペイロードが約 70% 削減され、日常的な作業は引き続きすべてカバーできます。DOKPLOY_READONLY=1 を設定すると、安全な監視専用プロファイル（GET ツールのみ）になります。

セットアップ

自動（推奨）：上記の「初回実行」セクションにあるセットアップスクリプトを実行すると、MCP が自動的に設定されます。

手動 — Claude の設定ファイル（Claude Code の場合は ~/.claude.json。claude mcp add-json を使えば自動で設定できます）の mcpServers オブジェクトに追加します。

{
  "mcpServers": {
    "dokploy": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@sattva/dokploy-mcp@latest"],
      "env": {
        "DOKPLOY_URL": "https://dokploy.example.com",
        "DOKPLOY_API_KEY": "<your-api-token>",
        "DOKPLOY_MODE": "gateway"
      }
    }
  }
}

注： DOKPLOY_URL に /api サフィックスは付けません。上部の警告を参照してください。 注： macOS/Linux では "command": "npx", "args": ["-y", "@sattva/dokploy-mcp@latest"] を使用してください。 ローカル開発： "command": "node", "args": ["<path>/dokploy-mcp/dist/index.js"]。 環境変数： DOKPLOY_MODE（tools/gateway/both）、DOKPLOY_TOOLS、DOKPLOY_READONLY、 DOKPLOY_TIMEOUT_MS、DOKPLOY_MAX_RESPONSE_CHARS。

MCP ツールのカテゴリ別一覧（Dokploy v0.28.4 時点の件数。v0.29.x では ai_*、forwardAuth_*、customRole_*、whitelabeling_*、patch_* などが約90件追加されています）

カテゴリ	ツール数	説明
application_*	29	アプリのライフサイクル、デプロイ、設定、Git プロバイダー
compose_*	28	Docker Compose サービス
settings_*	49	サーバー設定、Traefik、クリーンアップ、モニタリング
notification_*	38	Slack／Telegram／Discord／Email／Webhook／Gotify／Ntfy／Pushover／Lark／Teams
user_*	18	ユーザー管理、API キー、権限
server_*	16	リモートサーバー管理
postgres_*	14	PostgreSQL 管理
redis_*	14	Redis 管理
mysql_*	14	MySQL 管理
mariadb_*	14	MariaDB 管理
mongo_*	14	MongoDB 管理
patch_*	12	ファイルパッチ
backup_*	11	データベースのバックアップ
organization_*	10	組織、招待
sso_*	10	SSO／SAML エンタープライズ認証
domain_*	9	ドメイン／SSL 管理
ai_*	9	AI 搭載の Compose ジェネレーター
deployment_*	8	デプロイ履歴、キュー
project_*	8	プロジェクト管理
gitea_*	8	Gitea プロバイダー
docker_*	7	コンテナー操作
bitbucket_*	7	Bitbucket プロバイダー
registry_*	7	Docker レジストリ
gitlab_*	7	GitLab プロバイダー
stripe_*	7	課金（クラウド）
environment_*	7	プロジェクトごとの環境
github_*	6	GitHub プロバイダー
licenseKey_*	6	エンタープライズライセンス
sshKey_*	6	SSH キー管理
mounts_*	6	ボリュームマウント
destination_*	6	S3 バックアップ先
schedule_*	6	スケジュールタスク／cron
volumeBackups_*	6	ボリュームのバックアップ
certificates_*	4	SSL 証明書
cluster_*	4	Docker Swarm クラスター
port_*	4	ポート管理
redirects_*	4	URL リダイレクト
security_*	4	セキュリティ設定
previewDeployment_*	4	プレビューデプロイ
swarm_*	3	Swarm ノード情報
gitProvider_*	2	汎用 Git プロバイダー
rollback_*	2	デプロイのロールバック
admin_*	1	管理者のセットアップ

MCP デプロイワークフロー

1. application_one                → check current status
2. application_saveEnvironment    → set/update env vars if needed
3. application_saveBuildType      → ensure Dockerfile build configured
4. application_deploy             → trigger deployment
5. application_one                → poll until applicationStatus = "done"
6. curl health endpoint           → verify app is working

ログ — MCP から利用可能（v0.29.x）

ログはダッシュボード限定ではありません。v0.29.8 で確認済みで、すべて読み取り専用です。

ツール	取得内容
deployment_readLogs(deploymentId)	1件のデプロイのビルド／デプロイログ
application_readLogs(applicationId)	アプリケーションコンテナーのログ
compose_readLogs(composeId, containerId)	1つの Compose コンテナーのログ
postgres_readLogs / mysql_readLogs / mariadb_readLogs / mongo_readLogs / redis_readLogs	データベースサービスのログ

一般的な流れ：deployment_all(applicationId) → 最新の deploymentId を取得 → deployment_readLogs。ライブストリーミングのみ引き続き WebSocket 専用です。ビルドをリアルタイムで監視する必要がある場合は、ダッシュボードを使用してください。

MCP の残る制限事項

• コンテナー内での Docker exec — API エンドポイントがないため、VPS に SSH で接続してください

Redis、MariaDB、MongoDB、Compose、バックアップ、通知、スケジュール、ロールバック、SSO、パッチ、組織など、それ以外はすべて MCP ツールから利用できます。

よくある落とし穴

詳しい解決方法については、references/PITFALLS.mdを参照してください。

問題	原因	修正方法
すべてのMCP呼び出しが404になる	DOKPLOY_URL の末尾が /api になっているため、リクエストが /api/api/... に送信される	/api のサフィックスを削除する
COPY /app/public が失敗する	Gitは空のディレクトリを無視する	Dockerfileで RUN mkdir -p public を実行する
DB接続エラー	NeonのHTTPドライバーと標準のPGの違い	postgres（postgres.js）パッケージを使用する
Clerkの publishableKey がない	SSGがビルド時に環境変数を検証する	export const dynamic = "force-dynamic" を設定し、ビルドフェーズではプロバイダーをスキップする
migrate.mjsによるコンテナーのクラッシュ	standalone出力にモジュールが含まれていない	アプリ内APIエンドポイント経由でマイグレーションを実行する
ビルドログが必要	—	deployment.readLogs(deploymentId) を使用する。ライブストリーミングはWebSocketのみ
コンテナーログが必要	—	application.readLogs / compose.readLogs / <db>.readLogs を使用する
外部DBポートに接続できない	VPSのファイアウォールがポートをブロックしている	内部Dockerネットワーク名を使用する
curlでSSL証明書エラーが発生する	自己署名証明書、またはLet's Encryptの発行遅延	curl -sk を使用するか、証明書の発行を待つ
デプロイ後にAPIルートが404になる	ルートがstandalone出力に含まれていない	.next/standalone にルートがあることを確認する
アップグレード後にTraefikミドルウェアが動作しない	Dokploy v0.25以降はTraefik v3を使用する	ミドルウェア設定の構文を更新する

ビルドタイプ

Dokployは以下をサポートしています。

タイプ	用途
Dockerfile	カスタムビルド、マルチステージ、完全な制御
Nixpacks	言語を自動検出し、設定不要
Buildpack	Heroku/Paketo互換アプリ
Docker Image	レジストリから取得したビルド済みイメージ

サービス（データベース）

ダッシュボード → プロジェクト → サービスを追加、から作成します。

• PostgreSQL — 内部ホスト名：<appName>:5432
• MySQL/MariaDB — 内部ホスト名：<appName>:3306
• MongoDB — 内部ホスト名：<appName>:27017
• Redis — 内部ホスト名：<appName>:6379

内部ホスト名はDockerネットワークを使用します。外部ポートは任意です（ファイアウォールルールが必要になる場合があります）。

ドメインとSSL

1. ダッシュボードまたはAPI（domain.create）からドメインを追加する
2. DNSのAレコードをVPSのIPに向ける
3. DokployがTraefik v3経由でLet's Encrypt証明書を自動発行する
4. DNSの伝播後、HTTPSが自動的に機能する

Next.js固有のガイド

Next.js 14/15をDokployにデプロイする方法の詳細については、references/NEXTJS-GUIDE.mdを参照してください。