Doubao Image MCP Server

🚀 豆包画像生成MCPサーバー

FastMCPフレームワークと火山エンジンAPIに基づく画像生成MCPサーバーです。豆包（doubao - seedream - 3.0 - t2i）モデルを通じて高品質な画像生成をサポートします。

🚀 クイックスタート

このサーバーは、火山エンジンのAPIを利用して豆包の画像生成モデルを操作します。必要な環境設定と依存関係を正しく構築することで、高品質な画像生成を行うことができます。

✨ 主な機能

• 🎨 高品質な画像生成：豆包seedream - 3.0 - t2iモデルに基づき、2K解像度をサポートします。
• 🌐 二言語対応：プロンプトは中国語と英語の記述をサポートします。
• 📐 複数の解像度：512x512から2048x2048までの様々な解像度をサポートします。
• 🎯 精密な制御：シード、ガイダンススケール、透かしなどのパラメータ制御をサポートします。
• 📁 ローカル保存：生成された画像を自動的に指定されたディレクトリにダウンロードして保存します。
• 🔧 MCPプロトコル：MCPプロトコルと完全に互換性があり、MCP対応のAIアシスタントと統合できます。
• 📊 詳細なログ記録：完全なログ記録とエラーハンドリングが行われます。

📦 インストール

必要条件

• Python >= 3.13
• 火山エンジンAPIキー
• 推論エンドポイントモデルID

3.1 プロジェクトのクローン

git clone git@github.com:suibin521/doubao-image-mcp-server.git
cd doubao-image-mcp-server

3.2 インストール方法

方法1: uvxを使用して直接実行（推奨）

# PyPIから直接インストールして実行
uvx doubao-image-mcp-server

方法2: uvを使用してプロジェクトにインストール

# 現在のプロジェクトにインストール
uv add doubao_image_mcp_server

方法3: 開発者用インストール

# リポジトリをクローンした後、プロジェクトのルートディレクトリで実行
uv sync
# またはpipを使用
pip install -e .

方法4: 従来のpipインストール

pip install doubao_image_mcp_server

3.3 環境変数の設定

このプロジェクトでは.envファイルを使用せず、すべての設定はMCP JSON設定ファイルのenvフィールドを通じて渡されます。

3.3.1 環境変数設定例

"env": {
  "BASE_URL": "https://ark.cn-beijing.volces.com/api/v3",
  "DOUBAO_API_KEY": "your-dev-api-key-here",
  "API_MODEL_ID": "ep-20250528154802-c4np4",
  "IMAGE_SAVE_DIR": "C:/images"
}

3.3.2 環境変数の詳細説明

3.4 APIキーとモデルIDの取得

3.4.1 火山エンジンプラットフォームに登録

以下のURLを使用して火山プラットフォームにログインして登録します。右上隅で言語（中国語または英語）を選択できます。

https://console.volcengine.com/auth/signup

3.4.2 火山エンジンコンソールにログイン

登録後、火山エンジンコンソールにアクセスします。

https://console.volcengine.com/ark/region:ark+cn-beijing/overview?briefPage=0&briefType=introduce&type=new

3.4.3 画像生成モデル「Doubao - Seedream - 3.0 - t2i」を有効化する

1. システム管理 → 有効化管理画面に移動します。
2. ビジョン大規模モデルを選択します。
3. Doubao - Seedream - 3.0 - t2iモデルを見つけます。
4. 右側の「サービスを有効化する」ボタンをクリックしてサービスを有効化します。 アクセスリンク:

https://console.volcengine.com/ark/region:ark+cn-beijing/openManagement?LLM=%7B%7D&OpenTokenDrawer=false

3.4.4 推論エンドポイントを作成する

1. コンソールで、オンライン推論 → 推論エンドポイントを作成をクリックします。
2. 以下の情報を入力します。
   • エンドポイント名: エンドポイントに名前を付けます。
   • エンドポイントの説明: 説明情報を追加します。
   • モデル選択: 先ほど有効化したDoubao - Seedream - 3.0 - t2iモデルを選択します。
3. 作成ボタンをクリックしてエンドポイントを作成します。
4. 作成後、概要画面で対応するModel_id（形式: ep - m - 20250528154647 - cx5fg）を確認できます。

3.4.5 APIキーを作成する

1. コンソールの右側でAPIキー管理を選択します。
2. APIキーを作成をクリックします。
3. APIキーを生成して保存します（安全に保管し、漏洩しないでください）。

3.4.6 設定情報の取得完了

上記の手順を完了すると、以下の設定情報が取得できます。

• BASE_URL: https://ark.cn-beijing.volces.com/api/v3（固定値）
• DOUBAO_API_KEY: 先ほど作成したAPIキー
• API_MODEL_ID: 推論エンドポイントのModel_id（例: ep - m - 20250528154647 - cx5fg）
• IMAGE_SAVE_DIR: 画像保存ディレクトリのパス

💻 使用例

4.1 開発ツールでMCPサーバーを設定する

このサーバーは、VS Code + Cline、Cursor、TraeなどのさまざまなAI開発ツールでの使用をサポートしています。設定方法は以下の通りです。

4.1.1 MCP設定ファイルのセットアップ

MCP設定ファイルに以下の設定を追加します。

{
  "mcpServers": {
    "doubao_image_mcp_server": {
      "command": "uvx",
      "args": [
        "doubao-image-mcp-server"
      ],
      "env": {
        "BASE_URL": "https://ark.cn-beijing.volces.com/api/v3",
        "DOUBAO_API_KEY": "your-dev-api-key-here",
        "API_MODEL_ID": "ep-20250528154802-c4np4",
        "IMAGE_SAVE_DIR": "C:/images"
      }
    }
  }
}

4.1.2 開発ツールの設定手順

VS Code + Cline:

• VS Codeの設定でCline拡張機能の設定を見つけます。
• 上記のMCP設定をClineのMCPサーバー設定に追加します。

Cursor:

• Cursorの設定でMCP設定オプションを見つけます。
• 上記の設定を追加し、Cursorを再起動します。

Trae:

• 上記の設定をTraeのMCP設定ファイルに追加します。
• 保存後、設定ファイルを再読み込みします。

4.1.3 使用例

設定後、AIアシスタントに直接話しかけて画像を生成できます。

Cursorでの使用例:

1. エージェントモードに入ります。
2. まず、Cursorに画像生成ツールを理解させます: "Please understand the available image generation tools"
3. 次に、直接画像生成要求を行います: "Please help me generate a sunset seaside landscape image"

その他の開発ツールでの使用:

• AIアシスタントに生成したい画像を直接説明します。
• AIアシスタントは自動的に豆包画像生成ツールを呼び出します。
• 生成された画像は、設定したディレクトリに保存されます。

4.2 サーバーを独立して起動する

python doubao_mcp_server.py

4.3 MCPツールの呼び出し

サーバーは以下のMCPツールを提供します。

4.3.1 doubao_generate_image

画像生成の主要ツールです。

パラメータ:

• prompt (必須): 画像の説明テキストで、中国語と英語をサポートします。
• size (オプション): 画像の解像度で、デフォルトは "1024x1024" です。
• seed (オプション): 乱数シードで、指定しない場合はランダムな数が自動生成され、デフォルトは -1 です。
• guidance_scale (オプション): ガイダンススケール 1.0 - 10.0 で、デフォルトは 8.0 です。
• watermark (オプション): 透かしを追加するかどうかで、デフォルトは true です。
• file_prefix (オプション): ファイル名の接頭辞で、英語のみです。

サポートされる解像度:

• 512x512 - 512x512 (1:1 小さい正方形)
• 768x768 - 768x768 (1:1 正方形)
• 1024x1024 - 1024x1024 (1:1 大きい正方形)
• 864x1152 - 864x1152 (3:4 縦長)
• 1152x864 - 1152x864 (4:3 横長)
• 1280x720 - 1280x720 (16:9 ワイドスクリーン)
• 720x1280 - 720x1280 (9:16 モバイル縦長)
• 832x1248 - 832x1248 (2:3)
• 1248x832 - 1248x832 (3:2)
• 1512x648 - 1512x648 (21:9 超広角)
• 2048x2048 - 2048x2048 (1:1 超大きい正方形)

呼び出し例:

基本的な使用法

{
  "tool": "doubao_generate_image",
  "arguments": {
    "prompt": "A cute orange cat sitting on a sunny windowsill, watercolor style"
  }
}

高度な使用法

{
  "tool": "doubao_generate_image",
  "arguments": {
    "prompt": "A cute orange cat sitting on a sunny windowsill, watercolor style",
    "size": "1024x1024",
    "seed": -1,
    "guidance_scale": 8.0,
    "watermark": false,
    "file_prefix": "cute_cat"
  }
}

特定のシードを使用して画像を再現する場合:

{
  "tool": "doubao_generate_image",
  "arguments": {
    "prompt": "A cute orange cat sitting on a sunny windowsill, watercolor style",
    "seed": 1234567890,
    "size": "1024x1024"
  }
}

4.4 MCPリソース

4.4.1 resolutions

利用可能なすべての画像解像度のリストを取得します。

4.5 MCPプロンプトテンプレート

4.5.1 image_generation_prompt

画像生成のプロンプトテンプレートを提供し、すべてのパラメータの説明と使用例が含まれています。

📚 ドキュメント

プロジェクト構造

doubao-image-mcp-server/
├── doubao_mcp_server.py    # 主要なMCPサーバー
├── doubao_image_gen.py     # コアの画像生成ツール
├── pyproject.toml          # プロジェクトの設定と依存関係管理
├── uv.lock                 # 依存関係ロックファイル
├── .gitignore             # Gitの無視ファイル
├── LICENSE                # オープンソースライセンス
├── README.md              # 英語のプロジェクトドキュメント
├── README_CN.md           # 中国語のプロジェクトドキュメント
└── images/                # ドキュメントの画像ディレクトリ
    ├── create_api_key.jpg
    ├── create_inference_endpoint.jpg
    ├── model_activation.jpg
    └── volcengine_signup.jpg

ロギングシステム

このプロジェクトには完全なロギングシステムが含まれています。

• ファイルロギング: log/ ディレクトリに保存されます。
• コンソールロギング: デバッグ用にstderrに出力されます。
• ログレベル: DEBUG、INFO、WARNING、ERROR

エラーハンドリング

• ✅ 環境変数の検証
• ✅ パラメータの型と範囲のチェック
• ✅ API呼び出しエラーのハンドリング
• ✅ 画像ダウンロードのリトライメカニズム
• ✅ ファイル保存例外のハンドリング

技術的特徴

• 非同期処理: asyncioに基づく非同期画像生成
• リトライメカニズム: 画像ダウンロード失敗時の自動リトライ
• パラメータ検証: 完全な入力パラメータ検証
• モジュール化設計: コア機能をMCPサービスから分離
• 型アノテーション: 完全な型ヒントのサポート

よくある質問

Q: APIキーをどのように取得できますか？

A: 火山エンジンコンソールにアクセスし、API管理で新しいAPIキーを作成します。

Q: モデルIDはどこで見つけることができますか？

A: 火山エンジンコンソールで推論エンドポイントを作成した後、エンドポイントの詳細でIDを見つけることができます。

Q: どのような画像形式がサポートされていますか？

A: 現在、生成された画像はJPG形式で保存されます。

Q: 画像の保存パスをどのようにカスタマイズできますか？

A: 環境設定のIMAGE_SAVE_DIR変数を変更します。

Q: 生成が失敗した場合はどうすればいいですか？

A: ログファイルを確認し、APIキー、モデルID、およびネットワーク接続が正常に機能していることを確認します。

📄 ライセンス

このプロジェクトはMITライセンスの下でオープンソースです。

貢献

このプロジェクトを改善するために、IssuesとPull Requestsの投稿を歓迎します。