maginary-mcp

maginary-mcp

Maginary 用の Model Context Protocol サーバーです。画像と動画に特化した、抽象化された OpenRouter です。約20のモデルファミリー（GPT-image-2、Seedance 2、Sora 2、Nano Banana Pro、Flux…）を、Midjourney 風の --flag プロンプト1つで利用できます。16個のツールを備え、フラグの全カタログ、生成／アップスケール／バリエーション作成／アニメーション化、チャット内でのサインアップ、課金、ウォレットを持つエージェント向けの x402 従量課金に対応します。

デモを見る →

概要

Maginary は、非同期 HTTP API 上で Midjourney 風の --flag プロンプト DSL を使用します。このサーバーは次の機能を提供します。

• LLM にパラメーターの全カタログを提示し、適切なフラグを選択できるようにします
• POST /api/gens/ を呼び出す、1回で完結する generate ツールを提供します
• 終了状態までポーリングするための get_generation と wait_for_generation を提供します
• カタログツールはオフラインでも動作します（バンドルされたスナップショットを同梱し、起動時に接続可能であればライブドキュメントのエンドポイントから更新します）

接続

これは MCP サーバーです。直接実行するのではなく、AI クライアント（Claude Desktop、Cursor など）が起動して、バックグラウンドで通信します。設定ブロックを1つ追加するだけで、チャットを始められます。

Claude Desktop

Claude Desktop で、設定 → 開発者 → 設定を編集に進みます。claude_desktop_config.json が開きます（macOS：~/Library/Application Support/Claude/、Windows：%APPDATA%\Claude\）。次を追加します。

{
  "mcpServers": {
    "maginary": {
      "command": "uvx",
      "args": ["--upgrade", "maginary-mcp"]
    }
  }
}

Claude Desktop を再起動します。画像の生成を依頼すると、Maginary のツールが自動的に利用可能になります。

アカウントをお持ちでない場合も大丈夫です。 Claude がサインアップを案内します（メールアドレスを伝えるだけです）。すでに API キーをお持ちの場合は、次を追加してこの手順を省略できます。

"env": { "MAGINARY_API_KEY": "sk-mag-…" }

Python 3.10 以降と uv が必要です。代わりに pip install maginary-mcp も使用できます。

設定

設定は不要です。stdio サーバーで設定する変数は、最大でも1つです。

変数	デフォルト	説明
MAGINARY_API_KEY	—	app.maginary.ai/dashboard#api-keys で取得した Bearer トークンです。チャット内でのサインアップ手順を省略します。カタログツールはこれなしでも動作します。
MAGINARY_BASE_URL	https://app.maginary.ai/api	ステージング環境またはセルフホスト環境向けのオーバーライドです。
MAGINARY_MCP_LOG_LEVEL	INFO	標準的な Python のログレベルです。stderr に出力されます（stdout は MCP JSON-RPC 用に予約されています）。

それ以外の変数は、自分でホストするサーバー（maginary-mcp-http。後述）の実行時にのみ適用されます。コードをスキャンするディレクトリのページにも記載されていますが、ローカルでの使用時は無視してください。

変数（ホスト時のみ）	デフォルト	説明
MAGINARY_MCP_HOST / MAGINARY_MCP_PORT	0.0.0.0 / 8642	HTTP サーバーのバインドアドレスです。
MAGINARY_PUBLIC_HOST	app.maginary.ai	MAGINARY_BASE_URL が内部アドレスの場合、X-Forwarded-Host（-Proto／-For と併せて）としてバックエンドに送信され、バックエンドが公開 URL を構築できるようにします。
MAGINARY_MCP_REQUIRE_AUTH	オフ	オンの場合、すべての /mcp 呼び出しに Bearer（OAuth トークンまたは API キー）が必要です。未指定の場合、サーバーは /.well-known/oauth-protected-resource を示す WWW-Authenticate とともに 401 を返します。これにより Claude／ChatGPT はログインを開始します。ただし、ウォレットのみのエージェントには送信する Bearer がないため、このゲートがオンの場合は、まずプレーン HTTP（POST /api/gens/）で x402 決済を行い、その後 POST /api/auth/wallet-account/ で取得したキーを使って接続する必要があります。401 の本文にその旨が記載されています。
MAGINARY_OAUTH_ISSUER	https://app.maginary.ai/o	保護されたリソースのメタデータで指定される認可サーバー（バックエンドの django-oauth-toolkit）です。
MAGINARY_MCP_RESOURCE_URL	https://mcp.maginary.ai/mcp	このサーバーの正規リソース識別子（RFC 8707 audience）です。/.well-known/mcp/server-card.json が通知する値でもあります。

ホスト型（インストール不要） — Streamable HTTP

クライアントを https://mcp.maginary.ai/mcp のホスト型サーバーに直接接続します。 インストールは不要です。サーバーはマルチテナント対応のため、各リクエストは付随する認証情報に応じて処理されます。認証方法は2つあります。クライアントに合う方を選んでください。

接続（OAuth） — Claude Desktop、claude.ai、およびMCPのOAuth仕様に対応するその他のクライアント向けです。ヘッダーを指定せずにサーバーを追加します。

{
  "mcpServers": {
    "maginary": { "url": "https://mcp.maginary.ai/mcp" }
  }
}

クライアントで「接続」をクリックします。app.maginary.ai のログインページが開くので、サインインして要求されたスコープを承認してください。以降、クライアントがトークンを保持するため、キーの生成や貼り付けは不要です。サーバーが MAGINARY_MCP_REQUIRE_AUTH=1 を指定して実行されている必要があります。指定されていない場合、ログインは求められません。

APIキー — OAuthの手順に対応していないクライアント向け（またはログイン画面を操作したくない場合）です。app.maginary.ai/dashboard#api-keys でキーを生成し、自分で送信します。

{
  "mcpServers": {
    "maginary": {
      "url": "https://mcp.maginary.ai/mcp",
      "headers": { "Authorization": "Bearer sk-mag-…" }
    }
  }
}

接続後はどちらの方法も同じです。使えるツールもアカウントも共通です。カタログツールはどちらの方法でも認証情報なしで使えますが、generate／get_generation／wait_for_generation には認証情報が必要です。次のコマンドでホスト型サーバーを自分で実行できます。

ツール呼び出し中の支払い（MCP上のx402）

キーがなくても、generate を呼び出せます。クレジットがない場合（またはアカウントがない場合）、結果は isError: true となり、トップレベルにx402 PaymentRequired（accepts、resource、…）と error: "payment_required" が含まれます。x402対応のMCPクライアント（x402 SDKの x402MCPSession）は accepts[0] に署名し、_meta["x402/payment"] に支払い情報を含めて同じツールを再度呼び出します。サーバーはこれを PAYMENT-SIGNATURE としてバックエンドに転送します。バックエンドが検証してBase上で決済し、アカウントのないウォレットにはアカウントを作成します。決済結果には、オンチェーンの領収書が _meta["x402/payment-response"] と x402_receipt に含まれます。APIキーは返されません。以降のリクエストでは、ウォレット署名付きの認証ヘッダー（X-Wallet-Address、X-Wallet-Signature、X-Wallet-Timestamp）を使用します。 サーバーには支払い処理のロジックがありません。すべての処理はバックエンドの /api/gens/ コントラクトによって決まります。

ウォレット署名による認証

最初のx402支払いでウォレットのアカウントが作成された後は、以降のすべてのリクエストで、ウォレットの秘密鍵を使って短いメッセージに署名して認証します。各リクエストには次の3つのヘッダーが必要です。

ヘッダー	値
X-Wallet-Address	小文字にした0x形式のEVMアドレス（42文字）
X-Wallet-Signature	チャレンジ文字列に対するEIP-191 personal_sign の16進数値
X-Wallet-Timestamp	Unix秒（整数）

チャレンジ文字列は次のとおりです。

Maginary: authenticate <address> at <timestamp>. This does not move funds.

<address> は小文字にし、<timestamp> はヘッダーで送信するものと同じUnix秒にします。タイムスタンプはサーバーの時計との差が5分以内である必要があります（未来方向の時刻のずれは30秒まで許容されます）。APIキーを管理する必要はありません。ウォレット自体が認証情報です。

pip install "maginary-mcp[http]"
maginary-mcp-http          # serves /mcp on 0.0.0.0:8642 (MAGINARY_MCP_PORT to change)
# — or —
docker build -t maginary-mcp . && docker run -p 8642:8642 maginary-mcp

ホスト型サーバーでは MAGINARY_API_KEY は設定されません（キーはリクエストごとに渡されます）。また、/health、人間向けページ（GET /）、OAuth保護リソースメタデータ、およびMCPサーバーカード（/.well-known/mcp/server-card.json）も提供します。サーバーカードにはツール一覧と認証方式が含まれ、ベアURLをスキャンするディレクトリで利用できます。

Claude Skill

サーバーには、--flag DSL、モデルの選択、非同期のgenerate→pollフローを説明するAgent Skillが付属しています。

maginary-mcp --install-skill   # -> ~/.claude/skills/maginary-image-gen/SKILL.md

このスキルは単独で利用できます。MCPのない環境でも、DSLとREST APIの呼び出し（POST /gens/ → ポーリング）を利用できます。サーバーに接続されている場合、Claudeは代わりに search_parameters を呼び出して正確なフラグ一覧を取得し、generate／wait_for_generation をネイティブに実行します。再実行すると更新されます。--force を指定しない限り、ローカルでの編集内容は保護されます。 ソース：src/maginary_mcp/SKILL.md。

ツール

カタログ（認証不要）

• list_parameters(category?, status?, include_reserved=false) — カタログを一覧表示します
• search_parameters(query, category?, include_reserved=false) — 名前／別名／説明／例をテキスト検索します
• get_parameter(name) — 1つのフラグ（正式名称または別名）の完全なレコードを取得します

list_parameters の応答には categories／statuses の分類が含まれ、list／search の両方の応答には source（live と bundled-snapshot）が含まれます。

生成（認証が必要）

• generate(prompt, callback_url?) — POST /api/gens/。img2img に対応しています。プロンプトに画像 URL を含めてください。URL を複数指定すると、複数の入力画像を合成します。スタイルのみを転送する場合は --sref <url> を使用してください（img2img ではありません）。
• upload_image(file_path, filename?) — ローカル画像ファイルを読み込み、POST /api/images/upload/ でアップロードします。img2img プロンプトまたは --sref で使用する CDN URL を返します。stdio 接続のみ対応しています（ホスト環境では URL を直接使用するか、REST エンドポイントを使用してください）。
• execute_action(generation_uuid, action_type, parent_image_index?, prompt?, callback_url?) — POST /api/gens/{uuid}/actions/。完了した生成画像に対して後続処理（アップスケール、バリエーション作成、パン、ズーム、img2vid、再生成）を実行します。
• get_generation(uuid) — GET /api/gens/{uuid}/。応答には、スロットと有効なアクションタイプの対応を示す processing_result.available_actions が含まれます。
• wait_for_generation(uuid, timeout_s=45) — done／failed になるまでポーリングします。結果が timeout の場合は処理がまだ実行中です。再度呼び出してください。

使用例

設定後、MCP 対応クライアントで次のようにします。

「maginary カタログで、アスペクト比に関するものを検索してください。」

LLM は search_parameters("aspect") を呼び出し、値、例、対応モデルを含む --ar エントリを取得します。

「次に、フラッグシップモデルでシネマティックなポートレートを 16:9 で生成してください。」

LLM は generate("a cinematic portrait --ar 16:9 --flagship") を呼び出して uuid を取得し、続いて wait_for_generation(uuid) を呼び出して、最終レコードから image_urls[] を読み取ります。

「最初の画像をアップスケールしてください。」

LLM は processing_result.available_actions["0"] を確認して "upscale_2x" があることを確かめ、execute_action(uuid, "upscale_2x", 0) を呼び出して新しい uuid を取得し、続いて wait_for_generation(new_uuid) を呼び出します。

「この写真を水彩画風に編集してください。」 (ユーザーがローカル画像を提供)

LLM は upload_image("/tmp/photo.png") を呼び出して CDN URL を取得し、続いて generate("https://cdn.maginary.ai/…/photo.webp reimagine as watercolor painting") を呼び出します。(stdio のみ — ホスト環境では、ユーザーが代わりに URL を提供します。)

カタログの鮮度

• 起動時に https://maginary.ai/docs/parameters.json からライブ取得します。タイムアウトは 5 秒です。
• ライブ取得に失敗した場合（ネットワークがない、ドキュメントサイトが停止しているなど）は、フォールバックとして src/maginary_mcp/parameters_snapshot.json の同梱スナップショットを使用します。
• スナップショットは、メンテナーが python scripts/refresh_snapshot.py を実行して手動で更新します。新しいスナップショットが必ずレビュー済みのコミットに対応するよう、wheel のビルドには意図的に含めていません。

list_parameters／search_parameters の応答にある source フィールドから、どちらが有効かを確認できます。

開発

cd mcp
python -m venv venv && source venv/bin/activate
pip install -e .
maginary-mcp   # runs on stdio; kill with Ctrl+D

ライセンス

MIT。