Sora MCP

🚀 Sora MCP Server

このプロジェクトは、OpenAIのSora 2 APIを統合した、動画生成とリミックスに対応したModel Context Protocol (MCP) サーバーです。テキストプロンプトから動画を生成したり、既存の動画を新しいプロンプトでリミックスしたりすることができます。

🚀 クイックスタート

Sora MCP Serverを使用することで、Sora 2 APIを利用して動画の生成とリミックスを行うことができます。以下の手順に従ってサーバーをセットアップしてください。

✨ 主な機能

• 動画生成: Sora 2を使用して、テキストプロンプトから動画を生成します。
• 動画リミックス: 既存の動画に新しいプロンプトを適用して、バリエーションを作成します。
• 動画ステータス確認: 動画生成ジョブのステータスと進捗状況を確認します。

📦 インストール

前提条件

• Node.js 18+
• Soraにアクセス可能なOpenAI APIキー
• MCP互換クライアント (Claude、Cursor、VS Codeなど)

インストール手順

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

git clone https://github.com/Doriandarko/sora-mcp
cd sora-mcp

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

npm install

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

npm run build

4. Claude Desktop用に設定します:
   • claude_desktop_config.example.json を ~/Library/Application Support/Claude/claude_desktop_config.json にコピーします。
   • args パスをインストールディレクトリに合わせて更新します。
   • OPENAI_API_KEY フィールドにOpenAI APIキーを追加します。
   • オプションで DOWNLOAD_DIR を好みのダウンロードフォルダに設定します。

🔧 技術詳細

サーバーアーキテクチャ

このプロジェクトには、異なるユースケースに対応する 2つのサーバー実装 が含まれています。

📱 stdio-server.ts - Claude Desktop用

• 通信方式: stdio (標準入出力)
• ユースケース: ローカルプロセス間通信
• 動作原理: Claude Desktopが子プロセスとして起動します。
• 利点: 高速、セキュア、ネットワーク不要
• 使用クライアント: Claude Desktop

🌐 server.ts - リモートアクセス用

• 通信方式: HTTP/Streamable HTTP
• ユースケース: リモートクライアント、ウェブベースのツール
• 動作原理: ポート3000でHTTPサーバーとして実行されます。
• 利点: ネットワークアクセス可能、複数のクライアント対応
• 使用クライアント: MCP Inspector、VS Code、Cursor、ブラウザ

なぜ2つのサーバーが必要なのか？ 異なるMCPクライアントは異なる通信方式を使用します。この分離により、コードがクリーンに保たれ、各通信方式に最適化されます。

💻 使用例

Claude Desktop (stdioモード)

Claude Desktopは設定後に自動的にサーバーを起動します。以下のことを確認してください。

1. .env ファイルに OPENAI_API_KEY が設定されていること。
2. 設定を更新した後、Claude Desktopを再起動すること。

設定では src/stdio-server.ts が使用され、stdioを介して通信します。

HTTPモード (MCP Inspector、ウェブクライアント)

開発モードで自動リロード付きでサーバーを起動します:

npm run dev

本番モードで起動するには:

npm run build
npm start

MCPクライアントへの接続

Claude Desktop

サーバーはすでに設定されています。

設定内容: 設定ファイルは ~/Library/Application Support/Claude/claude_desktop_config.json にあります。

コンパイルされたサーバーを使用し、環境変数を介してAPIキーを渡します:

{
  "mcpServers": {
    "sora-server": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/sora-mcp/dist/stdio-server.js"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key-here",
        "DOWNLOAD_DIR": "/Users/yourname/Downloads/sora"
      }
    }
  }
}

完全な例は claude_desktop_config.example.json を参照してください。

環境変数:

• OPENAI_API_KEY (必須) - OpenAI APIキー
• DOWNLOAD_DIR (オプション) - カスタムダウンロードフォルダ (デフォルト: ~/Downloads)

使用方法:

1. Claude Desktopを再起動します (Cmd+Qで終了し、再度起動)。
2. Soraツールが自動的に表示されます。

MCP Inspector (テスト用)

MCP Inspectorを使用してサーバーをテストします:

npx @modelcontextprotocol/inspector

次に、http://localhost:3000/mcp に接続します。

Claude Code

claude mcp add --transport http sora-server http://localhost:3000/mcp

VS Code

code --add-mcp '{"name":"sora-server","type":"http","url":"http://localhost:3000/mcp"}'

Cursor

CursorのMCP設定に、stdio通信方式で追加します (Claude Desktopの設定と同様)。

利用可能なツール

create-video

テキストプロンプトから動画を生成します。

パラメーター:

• prompt (必須): 生成する動画のテキスト説明
• model (オプション): 使用するモデル (デフォルト: "sora-2")
• seconds (オプション): 動画の長さ (秒) (デフォルト: "4")
• size (オプション): 解像度 ("幅x高さ") (デフォルト: "720x1280")
• input_reference (オプション): 参照画像/動画のパス

例:

{
  "prompt": "A calico cat playing a piano on stage",
  "model": "sora-2",
  "seconds": "8",
  "size": "1024x1808"
}

get-video-status

動画生成ジョブのステータスと進捗状況を確認します。

パラメーター:

• video_id (必須): 確認する動画のID

例:

{
  "video_id": "video_123"
}

返り値: 動画のステータス (progress (0-100)、status (待機中/処理中/完了)、完了タイムスタンプを含む)

list-videos

ページネーションを使用して、すべての動画生成ジョブをリストします。

パラメーター:

• limit (オプション): 取得する動画の数 (デフォルト: 20)
• after (オプション): ページネーションのカーソル - このID以降の動画を取得
• order (オプション): ソート順 ("asc" または "desc") (デフォルト: "desc")

例:

{
  "limit": 10,
  "order": "desc"
}

download-video

完了した動画を手動でダウンロードするためのcurlコマンドを取得します。

パラメーター:

• video_id (必須): ダウンロードする動画のID
• variant (オプション): ダウンロードする形式 (デフォルト: MP4)

例:

{
  "video_id": "video_123"
}

返り値: 動画をダウンロードするための認証付きのcurlコマンド

save-video ⭐ (自動ダウンロード)

完了した動画を自動的にダウンロードしてコンピューターに保存します。

パラメーター:

• video_id (必須): 保存する動画のID
• output_path (オプション): 保存先のディレクトリ (デフォルト: ~/Downloads)
• filename (オプション): カスタムファイル名 (デフォルト: video_id.mp4)

例:

{
  "video_id": "video_123",
  "filename": "my-cat-video.mp4"
}

返り値: 動画が保存されたファイルパス。手動でのコマンドは不要です！

remix-video

既存の動画を新しいプロンプトでリミックスします。

パラメーター:

• video_id (必須): リミックスする完了した動画のID
• prompt (必須): リミックス用の新しいテキストプロンプト

例:

{
  "video_id": "video_123",
  "prompt": "Extend the scene with the cat taking a bow to the cheering audience"
}

delete-video

動画ジョブとそのアセットを削除します。

パラメーター:

• video_id (必須): 削除する動画のID

例:

{
  "video_id": "video_123"
}

典型的なワークフロー

1. 動画を作成する → video_id を取得します。

   "Create a video of a sunset over mountains"
   

2. ステータスを確認する → 進捗状況を監視します。

   "Check the status of video video_123"
   

3. 準備ができたら保存する → 動画ファイルを自動ダウンロードします。

   "Save video video_123"
   

   Claudeが自動的にダウンロードフォルダにダウンロードします！

4. 整理する → 古い動画を削除します。

   "Delete video video_123"
   

APIレスポンス形式

動画ジョブレスポンス

{
  "id": "video_123",
  "object": "video",
  "model": "sora-2",
  "status": "queued",
  "progress": 0,
  "created_at": 1712697600,
  "size": "1024x1808",
  "seconds": "8",
  "quality": "standard"
}

リミックスレスポンス

{
  "id": "video_456",
  "object": "video",
  "model": "sora-2",
  "status": "queued",
  "progress": 0,
  "created_at": 1712698600,
  "size": "720x1280",
  "seconds": "8",
  "remixed_from_video_id": "video_123"
}

エラーハンドリング

サーバーには包括的なエラーハンドリングが含まれています。

• 起動時のAPIキーの欠落チェック
• 詳細なメッセージを含むAPIエラーレスポンス
• ツールレスポンスでのエラーの適切な返却

開発

プロジェクト構造

sora-mcp/
├── src/
│   └── server.ts       # メインサーバー実装
├── dist/               # コンパイルされたJavaScript (自動生成)
├── package.json        # 依存関係とスクリプト
├── tsconfig.json       # TypeScript設定
├── .env               # 環境変数 (git管理外)
└── README.md          # このファイル

スクリプト

• npm run dev - tsxを使用して開発モードで実行
• npm run build - TypeScriptをJavaScriptにコンパイル
• npm start - コンパイルされたJavaScriptを実行

環境変数

• OPENAI_API_KEY (必須) - OpenAI APIキー
• PORT (オプション) - サーバーのポート (デフォルト: 3000)

📄 ライセンス

MIT

参考資料

• Model Context Protocol Documentation
• OpenAI Sora API Documentation
• MCP TypeScript SDK