piapi-mcp-server

piapi-mcp-server

PiAPI の API と連携する、Model Context Protocol（MCP）サーバーの TypeScript 実装です。PiAPI を使うと、Claude やその他の MCP 対応アプリから、Midjourney／Flux／Kling／LumaLabs／Udio／Chrip／Trellis でメディアコンテンツを直接生成できます。

機能（今後さらに追加予定）

注：動画生成など、時間のかかるツールは、Claude のタイムアウト制限により完了しない場合があります。

• 基本画像ツールキット
• 基本動画ツールキット
• テキスト／画像プロンプトから Flux 画像を生成
• テキスト／画像プロンプトから Hunyuan 動画を生成
• 画像プロンプトから Skyreels 動画を生成
• テキスト／画像プロンプトから Wan 動画を生成
• 動画から MMAudio の音楽を生成
• TTS Zero-Shot 音声生成
• Midjourney 画像生成
  • imagine
  • その他
• Kling の動画とエフェクトを生成
• Luma Dream Machine の動画を生成
• Suno の音楽を生成
• Suno の歌詞を生成
• Udio の音楽と歌詞を生成
• 画像から Trellis の 3D モデルを生成
• LLM 内でワークフローを計画

Claude Desktop の使用例

前提条件

• Node.js 16.x 以降
• npm または yarn
• PiAPI API キー（piapi.ai で取得できます）

インストール

Smithery 経由でインストール

Smithery 経由で Claude Desktop 用の PiAPI MCP Server を自動的にインストールするには：

npx -y @smithery/cli install piapi-mcp-server --client claude

手動インストール

1. リポジトリをクローンします。

git clone https://github.com/apinetwork/piapi-mcp-server
cd piapi-mcp-server

2. 依存関係をインストールします。

npm install

3. プロジェクトをビルドします。

npm run build

ビルド後、dist/index.js ファイルが生成されます。このファイルを Claude Desktop やその他のアプリケーションで設定できます。詳しい設定手順については、「使用方法」セクションを参照してください。

4. （任意）MCP Inspector でサーバーをテストします。

まず、プロジェクトのルートディレクトリに API キーを記載した .env ファイルを作成します。

PIAPI_API_KEY=your_api_key_here

次に、以下のコマンドを実行して MCP Inspector を起動します。

npm run inspect

コマンドを実行すると、MCP Inspector が http://localhost:5173（デフォルトポート：5173）で利用できるようになります。ブラウザーでこの URL を開いてテストを開始してください。Inspector の操作におけるデフォルトのタイムアウトは 10000ms（10 秒）です。画像生成タスクには不十分な場合があります。画像生成やその他の時間のかかる操作をテストするときは、タイムアウトを延長することをおすすめします。URL にタイムアウトパラメーターを追加すると調整できます。例： http://localhost:5173?timeout=60000（タイムアウトを 60 秒に設定）

MCP Inspector は、MCP サーバーの実装をテストしてデバッグするための強力な開発ツールです。主な機能は次のとおりです。

• 対話型テスト：ウェブインターフェースからサーバーの機能を直接テストできます
• リアルタイムフィードバック：関数呼び出しの結果や発生したエラーをすぐに確認できます
• リクエスト／レスポンスの確認：リクエストとレスポンスの詳細情報を表示できます
• 関数のドキュメント：利用可能な関数とそのパラメーターを確認できます
• カスタムパラメーター：タイムアウト値などの設定オプションをカスタマイズできます
• 履歴の追跡：過去の関数呼び出しとその結果を確認できます

MCP Inspector の使い方や機能の詳細については、MCP の公式ドキュメントを参照してください。

使用方法

Claude Desktop への接続

Claude Desktop の設定ファイル（macOS の場合は ~/Library/Application Support/Claude/claude_desktop_config.json、Windows の場合は %APPDATA%\Claude\claude_desktop_config.json）に以下を追加します。

{
  "mcpServers": {
    "piapi": {
      "command": "node",
      "args": ["/absolute/path/to/piapi-mcp-server/dist/index.js"],
      "env": {
        "PIAPI_API_KEY": "your_api_key_here"
      }
    }
  }
}

設定ファイルを更新した後は、Claude for Desktop を再起動してください。再起動すると、入力ボックスの右下にハンマーのアイコンが表示されます。 詳しい情報については、MCP の公式ドキュメントを参照してください。

Cursor への接続

注：以下のガイドは Cursor 0.47.5 に基づいています。機能や動作はバージョンによって異なる場合があります。

MCP サーバーを設定するには：

1. 「ファイル」>「環境設定」>「Cursor の設定」に移動するか、ショートカットキー Ctrl+Shift+J を使用します
2. 左側のパネルで「MCP」タブを選択します
3. 右上の「新しいグローバル MCP サーバーを追加」ボタンをクリックします
4. 開いた mcp.json ファイルに設定を追加します

{
  "mcpServers": {
    "piapi": {
      "command": "node",
      "args": ["/absolute/path/to/piapi-mcp-server/dist/index.js"],
      "env": {
        "PIAPI_API_KEY": "your_api_key_here"
      }
    }
  }
}

5. 設定後、MCP サーバーのページに「piapi」の項目が表示されます
6. 項目の「更新」ボタンをクリックするか、Cursor を再起動して piapi サーバーに接続します

piapi の画像生成をテストするには：

1. Cursor Chat で「エージェントモード」を開いて選択するか、ショートカットキー Ctrl+I を使用します
2. テスト用のプロンプトを入力します。例：「犬の画像を生成」
3. 入力したプロンプトに基づいて、piapi サーバーを使用して画像が生成されます

piapi サーバーを無効にするには：

1. Cursor の設定にある MCP サーバーのページに移動します
2. サーバー一覧から「piapi」の項目を探します
3. 「有効」の切り替えボタンをクリックして「無効」にします

PiAPI とのツール同期（同期タスク）

src/index.ts は、コミット済みのすべての PiAPI (model, task_type) 機能に対して、コントラクトに基づく MCP ツールを登録します。ツール名は piapi_<model>_<task_type> の形式で決定されます（例： piapi_qubico_flux1_schnell_txt2img）。入力スキーマはコミット済みのカタログから生成されます。既存の手書きの便利なツールも引き続き利用できます。コントラクトに基づくツールにより、Manager のカタログが変更されても、公開されるツール群を完全な状態に保てます。

src/index.ts の従来の便利なツールは引き続き手書きですが、コントラクトに基づくツール群全体はコミット済みのカタログから生成されます。このリポジトリには、カタログのベースラインと PiAPI Manager のバージョン管理された API コントラクトを比較する、再現可能な差分検出ツールが含まれています。新しい API、非推奨になった API、パラメーターの変更、説明の変更を検出します。

信頼できる唯一の情報源： PiAPI Manager の GitHub リポジトリ（Gocyber-world/midjourney-http-v2）にある Go API.postman_collection.json コントラクトです。このタスクは、そのバージョン管理されたコントラクトを GitHub から直接取得し、POST /api/v1/task の例を抽出して (model, task_type) の機能に変換します。Manager リポジトリが非公開の場合は、ソースリポジトリに対する最小権限の contents: read（および MCP 更新の自動化に必要な、別途承認された書き込み権限のみ）を持つ CI シークレット MCP_SYNC_GITHUB_TOKEN を設定してください。Apidog への依存はなく、価格の調査や報告も意図的に行いません。

コマンド

npm run build          # compile the MCP server and sync task
npm run test:sync      # offline sync-engine tests (no network or credentials)
npm run sync           # fetch contract and diff baseline; exit 0 = in sync, 2 = drift
npm run sync:snapshot  # print the normalized current contract catalog
npm run sync:report    # write the Markdown drift report to sync-report.md
npm run sync:accept    # after updating src/index.ts, refresh the baseline

デフォルトでは、npm run sync は Manager の GitHub コントラクトを使用します。復旧時やローカル開発では、代わりにエクスポートした OpenAPI JSON ファイルを指定できます。

node dist/sync/cli.js diff --file ./piapi-openapi.json

差分レポートが生成された場合、ベースラインの承認後、新しい機能はコントラクトに基づく MCP ツールとしてすでに反映されています。MCP サーバーを検証し、npm run sync:accept を実行して、更新したベースラインをコミットしてください。厳選されたモデル固有の UX が役立つ場合に限り、手書きの便利なツールを更新してください。

自動化

.github/workflows/sync-piapi.yml は手動実行専用として維持されています。定期的な同期は、承認済みのローカル自動化環境で実行されます。この環境は、別途オーナーの承認を得た MCP 認証情報を保持しており、機密情報チェックのゲートを通過した後、カタログの更新を検証、承認、プッシュできます。

開発

プロジェクト構成

piapi-mcp-server/
├── assets/
├── src/
│   ├── index.ts        # Main server entry point
│   └── sync/           # PiAPI -> MCP sync task
│       ├── cli.ts          # CLI: snapshot / diff / accept / report-file
│       ├── fetchers.ts     # GitHub Postman contract + local-file sources
│       ├── normalize.ts    # OpenAPI -> (model, task_type) catalog
│       ├── diff.ts         # catalog diff + Markdown report
│       ├── catalog.ts      # baseline load/save
│       ├── mcp_tools.ts    # catalog -> contract-backed FastMCP tool schemas
│       ├── selftest.ts     # offline engine test (npm run test:sync)
│       ├── types.ts
│       └── baseline.piapi-catalog.json  # committed baseline
├── .github/workflows/sync-piapi.yml     # weekly drift check
├── package.json
├── tsconfig.json
└── .env.example

ライセンス

MIT