Pixapi

pixapi-mcp

MCP クライアントから Pixapi の画像・動画生成ツールを使用できます。

• ウェブサイト：Pixapi
• リモート MCP エンドポイント：https://api.pixapi.ai/mcp
• ライセンス：MIT

クイックスタート

プロジェクトを自動設定します（Node.js 22 以上）。

npx -y pixapi-mcp init --client codex

codex を使用するクライアント名に置き換えるか、--client all を指定すると、5 つすべてのクライアントを対象にできます。

クライアント	--client	設定ファイル
Claude Code	claude-code	.mcp.json
Cursor	cursor	.cursor/mcp.json
Codex	codex	.codex/config.toml
VS Code / GitHub Copilot	vscode	.vscode/mcp.json
Gemini CLI	gemini-cli	.gemini/settings.json

--client を指定しない場合、デフォルトでは Claude Code と Cursor が選択されます（--client both）。 別のプロジェクトを設定するには、--project /path/to/project を使用してください。

MCP クライアントを再読み込みして pixapi に接続します。初回は、ブラウザーでのサインインと認可のプロンプトを完了してください。 クライアントが OAuth セッションを保存し、自動的に更新するため、API キーや認証情報を編集する必要はありません。 認可が取り消された場合や期限切れになった場合、クライアントから再度サインインを求められることがあります。 各クライアントは、それぞれのネイティブ OAuth セッションを管理します。

init はデフォルトで、直接接続するリモート HTTP 接続を設定します。 クライアントに「MCP サーバーを追加」インターフェースがある場合は、この npm パッケージや Node.js をインストールせずに、そこへエンドポイント URL を入力することもできます。

Codex では、信頼済みプロジェクトが必要です。VS Code では MCP: List Servers を使用して pixapi を起動し、Gemini CLI では /mcp を使用して状態を確認します。クライアントの信頼確認やサインインのプロンプトが表示された場合は、完了してください。init はクライアントのセキュリティポリシーを変更しません。

生成される設定

Claude Code：

{"mcpServers":{"pixapi":{"type":"http","url":"https://api.pixapi.ai/mcp"}}}

Cursor では、type フィールドを含めずに、同じ mcpServers エントリーで url を使用します。 VS Code では、servers と type: "http"、url を使用します。 Gemini CLI では、mcpServers と httpUrl を使用します。

Codex：

[mcp_servers.pixapi]
url = "https://api.pixapi.ai/mcp"

init を実行すると、他のサーバーや設定を保持したまま、pixapi エントリーが更新されます。VS Code の JSONC コメントは保持されます。Codex の TOML 設定は保持されますが、コメントと書式は保持されません。書き込み前に選択したすべての設定が解析されますが、書き込み中にファイルシステムでエラーが発生すると、一部のファイルだけが更新されることがあります。ローカルの問題を修正してから、init を再実行してください。

ローカル stdio ブリッジ

stdio が必要なクライアントでは、ブリッジを明示的に設定します。

npx -y pixapi-mcp init --client cursor --transport stdio

生成されるエントリーは、認証情報なしで npx -y pixapi-mcp proxy を実行します。npm パッケージをレジストリからインストールした場合も、ブリッジが直接起動するため、別途 init コマンドや環境変数を設定する必要はありません。

ブリッジは、ローカル MCP ハンドシェイクをすぐに完了します。最初のツールリクエスト時にブラウザー認証を開始し、その後ツールのリクエストを Pixapi に転送します。以降の接続では、保存済みのセッションを再利用し、トークンを自動的に更新します。ツール検出のタイムアウトが短いクライアントでは、事前に一度サインインしてください。

npx -y pixapi-mcp login

最初のブラウザーサインイン中にクライアントがタイムアウトした場合は、サインインを完了してからクライアントを再接続してください。認可 URL、コード、トークンが MCP の標準出力やエラー出力に表示されることはありません。

OAuth セッションは、エンドポイントごとに ~/.pixapi/oauth-<hash>.json に保存されます。 macOS と Linux では、ディレクトリのモードは 0700、ファイルのモードは 0600 です。 書き込みはアトミックに行われ、同時に実行されるブリッジプロセスは認可ロックを共有します。 PKCE 検証子とコールバック状態は、メモリー内だけに保持されます。コールバックは、ブリッジと同じホスト上のループバックにバインドされます。ヘッドレスホストまたはリモートホストでは、クライアントのネイティブなリモート OAuth 接続を使用してください。

既存の API キーを使用したインストール

既存の API キー設定との互換性は維持されています。API キーを明示してインストールする場合は、init の実行時に PIXAPI_API_KEY を設定してください。これにより stdio が設定され、キーが ~/.pixapi/mcp-credentials.json に非公開で保存されます。--transport remote を明示すると、この変数が設定されていても常にネイティブ OAuth が選択されます。プロキシでは、無人環境でのデプロイ向けに PIXAPI_API_KEY を直接指定することもできます。

プロキシは、明示的に指定された環境変数のキー、保存済みの OAuth セッション、従来のキーファイルの順に優先します。既存のブリッジを OAuth に移行するには、pixapi-mcp login を実行し、環境から PIXAPI_API_KEY の上書き設定を削除してください。生成されるプロジェクト設定にキーやトークンが含まれることはありません。

利用可能なツール

このパッケージは、Pixapi のリモート MCP エンドポイントから最新のツール一覧を転送します。接続後、最新のカタログを取得するには tools/list または pixapi_get_pricing_and_balance を呼び出してください。

pixapi_get_pricing_and_balance

現在の残高と、最新の画像・動画モデルの料金を返します。カタログの各行には type が含まれます。

• 画像：text_to_image、image_to_image
• 動画：text_to_video、image_to_video

mcp_generate_supported=true と記載された行のモデルは、対応する生成ツールから呼び出せます。

pixapi_generate_image

非同期の画像タスクを開始し、task_id を返します。プロンプトのみのリクエストには type=text_to_image を、image フィールドを使うリクエストには type=image_to_image を使用してください。このツールは、Gemini、GPT Image、Flux、Seedream、Qwen、Wan など、最新のカタログにある画像モデルに対応しています。

この呼び出しではアカウントのクレジットが消費されます。冪等ではないため、同じ呼び出しを繰り返すと別のタスクが作成され、アカウントに再度請求される場合があります。

pixapi_generate_video

非同期の動画タスクを開始し、task_id を返します。プロンプトのみのリクエストには type=text_to_video を、image フィールドを使うリクエストには type=image_to_video を使用してください。選択したモデルが必要とする seconds と resolution を渡してください。

この呼び出しではアカウントのクレジットが消費され、冪等ではありません。

pixapi_get_task

認証済みアカウントが所有する画像または動画タスクを取得します。返された task_id を使って、このツールをポーリングし、ステータスが completed または failed になるまで確認してください。タスクが完了すると、メディアの URL が含まれます。

エージェントの推奨フロー：

1. pixapi_get_pricing_and_balance を呼び出します。
2. mcp_generate_supported=true のカタログ行を選択し、残高を確認します。
3. pixapi_generate_image または pixapi_generate_video を一度だけ呼び出し、返された task_id を保持します。
4. 数秒おきに pixapi_get_task をポーリングします。
5. タスクが完了したら、結果の URL を返します。

CLI リファレンス

pixapi-mcp init [--client <name|all|both>] [--project <path>] [--transport <remote|stdio>]
pixapi-mcp login
pixapi-mcp proxy
pixapi-mcp --help

引数なしで実行すると、このパッケージは stdio プロキシを起動します。

トラブルシューティング

• ツールが表示されない： クライアントを再読み込みし、pixapi サーバーを有効にして、プロジェクトの信頼確認とブラウザーでのサインインを完了してください。stdio の場合は、ブリッジを実行するホストで Node.js 22+ と npx を利用できることを確認してください。
• 認証が拒否された、またはタイムアウトした： ネイティブクライアントからサインインを再試行するか、ブリッジで pixapi-mcp login を実行してブラウザー認証を完了してください。
• コールバック用ポートを利用できない： 保留中の別の Pixapi ログインを閉じてから再試行してください。
• サービスを利用できない： 接続を確認し、しばらくしてから再試行してください。内部の HTTP レスポンスと例外の詳細は、一般向けのエラーには含まれません。
• 従来の API キーが無効： キーを置き換えるか、上記の手順で OAuth に移行してください。

セキュリティと現在の制限事項

• ~/.pixapi/ 内のファイルをコミットしたり、共有したりしないでください。
• 使用していない認証情報や漏えいした認証情報は、Pixapi アカウントで取り消してください。
• stdio ブリッジが転送するのはツールのみです。このパッケージでは、リソース、プロンプト、サンプリング、エリシテーションは公開されません。
• 画像と動画の生成は非同期であり、冪等ではありません。ブリッジは HTTP 認証拒否を一度だけ再試行します。ネットワーク障害や、ツールの実行後に発生した可能性があるサーバーエラーは再試行しません。
• アカウントへのチャージは MCP ツールとして公開されていません。Pixapi で支払いを完了してください。

サービスのドキュメントについては、Pixapi のドキュメントをご覧ください。

公式 MCP レジストリ

このサーバーは公式 MCP レジストリにio.github.Pixapi-AI/pixapi-mcpとして公開されており、server.jsonで両方の接続方法（リモートエンドポイントと npm パッケージ）が宣言されています。どちらも、バージョン 0.1.4 以降では必須の API キーなしで OAuth を利用できます。

curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.Pixapi-AI/pixapi-mcp"

対応するv*タグをプッシュする前に、package.json、package-lock.json、server.jsonで同じバージョンを設定してください。リリースワークフローでは、ロックされた依存関係をインストールし、チェックを実行してから、公開前にレジストリマニフェストを検証します。手動で実行する場合も、そのリリースタグを選択する必要があります。再実行時には既存の npm パッケージの整合性とレジストリのメタデータを比較し、未完了の手順のみを公開します。内容が競合する場合は、新しいバージョンが必要です。レジストリの認証には GitHub OIDC を使用し、保存されたレジストリトークンは使用しません。