Seedream MCP

🚀 Seedream 4.0 MCP ツール (拡張版)

このツールは、火山エンジンの Seedream 4.0 API をベースにした MCP（Model Context Protocol）ツールセットで、文書から画像の生成、画像から画像の生成、複数画像の融合、画像シーケンスの生成などの機能を提供します。

謝辞: このプロジェクトは tengmmvp/Seedream_MCP をベースに拡張開発されており、原作者の貢献に感謝いたします！

拡張機能:

• ✨ 七牛雲への自動アップロードと公開アクセス
• 🎨 プロンプトテンプレートシステム (8つの事前設定テンプレート)
• 📸 Raycast AI Markdown 画像レンダリングサポート
• 💾 最適化された画像保存と管理

🚀 クイックスタート

MCP クライアントでの使用 (推奨)

MCP クライアントを設定した後、自然言語で会話して画像を生成できます。

例 1: 基本的な文書から画像の生成

あなたが言う:

可愛い小さな恐竜の画像を生成してください。友好的な表情で、カートゥーンスタイル。

AI の返答:

✅ 画像生成成功！

• プロンプト: 可愛い小さな恐竜、友好的な表情、カートゥーンスタイル
• サイズ: 2K
• 七牛雲リンク: https://newimg.t5t6.com/seedream/...
• ローカル保存先: seedream_images/2025-11-18/text_to_image/...

例 2: プロンプトテンプレートの使用

あなたが言う:

潮流パーティー、キーワード: コカ・コーラ

AI の返答:

✅ 画像生成成功！

• プロンプト: 「コカ・コーラ」、潮流パーティースタイルのアートフォント...
• サイズ: 2K (デフォルト 16:9)
• 七牛雲リンク: https://newimg.t5t6.com/seedream/...

例 3: ブログ記事の表紙

あなたが言う:

ブログ記事の表紙、テーマ: AI 技術革新

AI の返答:

✅ 画像生成成功！

• プロンプト: 「AI 技術革新」、ブログ記事の表紙スタイル...
• サイズ: 2K (自動的に 21:9 の比率が使用されます)
• 七牛雲リンク: https://newimg.t5t6.com/seedream/...

利用可能なプロンプトテンプレート

テンプレート名 + キーワードを直接入力するだけです。

MCP サーバーとして実行

python -m seedream_mcp.server

コード内での使用

import asyncio
from seedream_mcp import SeedreamClient, SeedreamConfig

async def main():
    # 設定の読み込み
    config = SeedreamConfig.from_env()

    # クライアントの作成
    client = SeedreamClient(config)

    try:
        # 文書から画像の生成（自動保存を有効にする）
        result = await client.text_to_image(
            prompt="可愛い小さな猫、カートゥーンスタイル",
            size="2K",
            watermark=False,
            auto_save=True,
            custom_name="cute_cat"
        )
        print(f"生成された画像のURL: {result['image_url']}")
        print(f"ローカル保存先: {result['local_path']}")
        print(f"Markdown引用: {result['markdown']}")

        # 画像から画像の生成
        result = await client.image_to_image(
            prompt="この画像を油絵スタイルに変換してください",
            image="path/to/image.jpg",
            size="2K",
            auto_save=True
        )
        print(f"変換後の画像のURL: {result['image_url']}")
        print(f"ローカル保存先: {result['local_path']}")

    finally:
        await client.close()

if __name__ == "__main__":
    asyncio.run(main())

✨ 主な機能

• 🎨 文書から画像の生成：テキスト記述に基づいて高品質の画像を生成します。
• 🖼️ 画像から画像の生成：参照画像とテキスト指示に基づいて新しい画像を生成します。
• 🎭 複数画像の融合：複数の参照画像の特徴を融合して新しい画像を生成します。
• 📚 画像シーケンスの生成：関連する内容の画像シーケンスを生成します。
• 💾 自動保存：生成された画像を自動的にダウンロードしてローカルに保存し、URL の有効期限切れの問題を解決します。
• ☁️ 七牛雲へのアップロード：オプションの七牛雲ストレージ統合機能で、画像を自動的にアップロードし、公開アクセス可能な URL を生成します。
• 📝 Markdown サポート：画像の Markdown 引用形式を自動的に生成します（七牛雲 URL とローカルパスの両方をサポート）。
• 🔧 完全な MCP プロトコルサポート：MCP 標準に準拠しており、MCP をサポートするクライアントとシームレスに統合できます。
• 🖼️ 直接画像表示：MCP ImageContent タイプをサポートし、クライアントで直接画像をプレビューできます。

📦 インストール

1. プロジェクトのクローン

git clone <repository-url>
cd Seedream_MCP

2. 依存関係のインストール

pip install -e .

3. 環境変数の設定

.env ファイルを作成します。

# 必須設定
ARK_API_KEY=your_api_key_here

# オプション設定
ARK_BASE_URL=https://ark.cn-beijing.volces.com/api/v3
SEEDREAM_MODEL_ID=doubao-seedream-4-0-250828
SEEDREAM_DEFAULT_SIZE=2K
SEEDREAM_DEFAULT_WATERMARK=false
SEEDREAM_TIMEOUT=60
SEEDREAM_API_TIMEOUT=60
SEEDREAM_MAX_RETRIES=3
LOG_LEVEL=INFO
LOG_FILE=logs/seedream_mcp.log

# 自動保存設定
SEEDREAM_AUTO_SAVE_ENABLED=true
SEEDREAM_AUTO_SAVE_BASE_DIR=./seedream_images
SEEDREAM_AUTO_SAVE_DOWNLOAD_TIMEOUT=30
SEEDREAM_AUTO_SAVE_MAX_RETRIES=3
SEEDREAM_AUTO_SAVE_MAX_FILE_SIZE=52428800
SEEDREAM_AUTO_SAVE_MAX_CONCURRENT=5
SEEDREAM_AUTO_SAVE_DATE_FOLDER=true
SEEDREAM_AUTO_SAVE_CLEANUP_DAYS=30

# 七牛雲設定（オプション、画像を七牛雲ストレージにアップロードするため）
QINIU_ACCESS_KEY=your_access_key
QINIU_SECRET_KEY=your_secret_key
QINIU_BUCKET_NAME=your_bucket_name
QINIU_DOMAIN=https://your-domain.com

⚠️ 重要提示

七牛雲を設定すると、生成された画像は自動的に七牛雲にアップロードされ、返される結果に公開アクセス可能な Markdown 画像リンクが提供されます。詳細は 七牛雲統合ドキュメント を参照してください。

4. MCP クライアントの設定

MCP クライアントの設定ファイルに以下の設定を追加します。

Raycast AI / Claude Desktop / Cline など:

{
  "mcpServers": {
    "seedream": {
      "command": "python",
      "args": [
        "/你的路径/Seedream_MCP/main.py"
      ],
      "env": {
        "ARK_BASE_URL": "https://ark.cn-beijing.volces.com/api/v3"
      }
    }
  }
}

設定ファイルの場所:

• Raycast AI: ~/Library/Application Support/com.raycast.macos/mcp.json
• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
• Cline (VSCode): .vscode/settings.json またはユーザー設定

⚠️ 重要提示

• /你的路径/Seedream_MCP/main.py を実際のプロジェクトパスに置き換えてください。
• Python 環境にすべての依存関係がインストールされていることを確認してください。
• 設定を完了したら、MCP クライアントを再起動してください。

📚 ドキュメント

🎨 プロンプトテンプレートシステム

8つの専用プロンプトテンプレートが組み込まれており、テンプレート名 + キーワードを入力するだけで、対応するスタイルの画像を生成できます。

• 潮流パーティー: オペレーション活動スタイルのアートフォント
• ブログ記事の表紙: 自動的に 21:9 の比率が使用され、ブログ記事の画像に適しています。
• 国潮スタイル: 中国の伝統要素と現代デザインが結合されています。
• 小清新: 文芸的で清新なスタイル
• サイバーパンク: 科学技術的な未来スタイル
• 新年の喜び: 祝祭行事スタイル
• ビジネスシンプル: 専門的なビジネスシーン
• 水彩イラスト: 手描きイラストスタイル

☁️ 七牛雲自動アップロード

七牛雲を設定すると、生成された画像は自動的に七牛雲ストレージにアップロードされます。

• ✅ 公開アクセス可能な永久リンクを生成します。
• ✅ Markdown 画像形式を自動的に生成します。
• ✅ Raycast AI で直接画像をレンダリングすることができます。
• ✅ ローカルとクラウドの両方に保存されます。

💾 スマート画像管理

• 自動保存: 画像は自動的にローカルにダウンロードされ、URL の有効期限切れを回避します。
• 日付別分類: 自動的に年/月のフォルダが作成されます。
• 自動クリーンアップ: 古い画像を自動的に削除することができます。
• 並列ダウンロード: 複数の画像を並列でダウンロードし、効率を向上させます。

ツール説明

1. seedream_text_to_image

テキスト記述に基づいて画像を生成します。

パラメータ：

• prompt (必須): テキスト記述、300 文字または 600 英単語以内を推奨
• size (オプション): 画像サイズ、選択可能な値：1K、2K、4K、デフォルト 2K
• watermark (オプション): ウォーターマークを追加するかどうか、デフォルト false
• response_format (オプション): 応答形式、選択可能な値：image、url、b64_json、デフォルト image
• auto_save (オプション): 画像を自動的にローカルに保存するかどうか、デフォルトではグローバル設定が使用されます。
• save_path (オプション): カスタム保存パス、指定しない場合はデフォルトパスが使用されます。
• custom_name (オプション): カスタムファイル名の接頭辞

自然言語の例：

可愛い小さな猫、カートゥーンスタイルの画像を生成してください。

またはプロンプトテンプレートを使用する：

潮流パーティー、キーワード: コカ・コーラ

2. seedream_image_to_image

参照画像とテキスト指示に基づいて新しい画像を生成します。

パラメータ：

• prompt (必須): 画像編集指示
• image (必須): 参照画像の URL またはローカルファイルパス
• size (オプション): 出力画像のサイズ、デフォルト 2K
• watermark (オプション): ウォーターマークを追加するかどうか、デフォルト false
• response_format (オプション): 応答形式、選択可能な値：image、url、b64_json、デフォルト image
• auto_save (オプション): 画像を自動的にローカルに保存するかどうか、デフォルトではグローバル設定が使用されます。
• save_path (オプション): カスタム保存パス、指定しない場合はデフォルトパスが使用されます。
• custom_name (オプション): カスタムファイル名の接頭辞

例：

{
  "prompt": "この画像を油絵スタイルに変換してください",
  "image": "https://example.com/image.jpg",
  "size": "2K",
  "watermark": false,
  "auto_save": true,
  "custom_name": "oil_painting"
}

3. seedream_multi_image_fusion

複数の参照画像の特徴を融合して新しい画像を生成します。

パラメータ：

• prompt (必須): 融合指示の記述
• images (必須): 複数の参照画像の URL またはファイルパスの配列（2 - 5 枚）
• size (オプション): 出力画像のサイズ、デフォルト 2K
• auto_save (オプション): 画像を自動的にローカルに保存するかどうか、デフォルトではグローバル設定が使用されます。
• save_path (オプション): カスタム保存パス、指定しない場合はデフォルトパスが使用されます。
• custom_name (オプション): カスタムファイル名の接頭辞

例：

{
  "prompt": "これらの画像をアート作品に融合してください",
  "images": [
    "https://example.com/image1.jpg",
    "https://example.com/image2.jpg",
    "https://example.com/image3.jpg"
  ],
  "size": "4K",
  "auto_save": true,
  "custom_name": "fusion_art"
}

4. seedream_sequential_generation

関連する内容の画像シーケンスを生成します。

パラメータ：

• prompt (必須): 画像シーケンス生成の記述
• max_images (オプション): 最大画像数（1 - 10）、デフォルト 3
• images (オプション): 参照画像の配列
• size (オプション): 画像サイズ、デフォルト 2K
• auto_save (オプション): 画像を自動的にローカルに保存するかどうか、デフォルトではグローバル設定が使用されます。
• save_path (オプション): カスタム保存パス、指定しない場合はデフォルトパスが使用されます。
• custom_name (オプション): カスタムファイル名の接頭辞

例：

{
  "prompt": "科学幻想都市の景観、未来主義スタイル",
  "max_images": 4,
  "size": "2K",
  "auto_save": true,
  "custom_name": "sci_fi_city"
}

設定オプション

自動保存機能

自動保存機能は、生成された画像の URL が 24 時間後に期限切れになる問題を解決し、永続的に利用可能なローカル画像ストレージを提供します。

核心特性

• 自動ダウンロード：画像が生成された後、自動的に指定されたローカルディレクトリにダウンロードされます。
• スマート命名：タイムスタンプ + 内容ハッシュ + サイズ情報の命名規則が使用されます。
• ディレクトリ管理：ツールタイプと日付に基づいて自動的に分類されて保存されます。
• Markdown サポート：ローカル画像の Markdown 引用形式が自動的に生成されます。
• エラー回復：ダウンロードが失敗した場合、元の URL が代替として提供されます。
• 並列ダウンロード：複数の画像を並列でダウンロードすることができます。

使用例

# 自動保存を有効にした文書から画像の生成
result = await client.text_to_image(
    prompt="美しい風景画",
    auto_save=True,
    custom_name="landscape"
)

# 返される結果には以下が含まれます：
# - image_url: 元の画像のURL
# - local_path: ローカル保存先
# - markdown: Markdown引用形式
# - save_result: 保存操作の詳細情報

ファイル構造

images/
├── 2024-01-15/
│ ├── text_to_image/
│ │ ├── landscape_20240115_143022_abc123_2K.png
│ │ └── portrait_20240115_143045_def456_4K.png
│ ├── image_to_image/
│ │ └── style_transfer_20240115_144001_ghi789_2K.png
│ └── multi_image_fusion/
│ └── fusion_art_20240115_145030_jkl012_4K.png
└── 2024-01-16/
└── ...

設定説明

• SEEDREAM_AUTO_SAVE_ENABLED: 自動保存をグローバルに有効または無効にする
• SEEDREAM_AUTO_SAVE_BASE_DIR: 画像を保存するルートディレクトリ
• SEEDREAM_AUTO_SAVE_DATE_FOLDER: 日付別のサブフォルダを作成するかどうか
• SEEDREAM_AUTO_SAVE_MAX_FILE_SIZE: ダウンロードする最大ファイルサイズを制限する
• SEEDREAM_AUTO_SAVE_MAX_CONCURRENT: 並列ダウンロード数を制御する
• SEEDREAM_AUTO_SAVE_CLEANUP_DAYS: 指定された日数を超える古いファイルを自動的に削除する

エラー処理

ツールは完全なエラー処理メカニズムを提供します。

• パラメータ検証エラー：必須パラメータとパラメータ形式をチェックします。
• API 呼び出しエラー：ネットワークエラー、タイムアウトなどの問題を処理します。
• 認証エラー：API キーが無効または期限切れです。
• クォータエラー：API 呼び出し回数が制限を超えています。
• サーバーエラー：火山エンジンのサービスが異常です。

ログ記録

ツールは詳細なログ記録をサポートします。

• 関数呼び出しログ
• API リクエストとレスポンスログ
• エラーと例外ログ
• パフォーマンス監視ログ

ログレベルは LOG_LEVEL 環境変数で設定できます。

🔧 技術詳細

開発とテスト

テストの実行

# 統合テストの実行
python tests/test_mcp_integration.py

# 検証スクリプトの実行
python verify_installation.py

プロジェクト構造

Seedream_MCP/
├── seedream_mcp/           # 主要なコード
│   ├── __init__.py
│   ├── client.py           # APIクライアント
│   ├── config.py           # 設定管理
│   ├── server.py           # MCPサーバー
│   ├── tools/              # ツールの実装
│   └── utils/              # ユーティリティ関数
├── docs/                   # ドキュメントディレクトリ
├── tests/                  # テストファイル
├── examples/               # 使用例
├── verifys/                # 検証スクリプト
├── .env.example           # 環境変数の例
├── main.py                # メインプログラムのエントリポイント
├── requirements.txt       # 依存関係のリスト
└── README.md             # 説明ドキュメント

よくある質問

Q: 画像が Raycast AI で表示されない場合はどうすればいいですか?

A: 以下を確認してください。

1. 七牛雲を設定していること（画像に公開アクセス可能な URL が必要）
2. 七牛雲のドメイン設定が正しいこと
3. Raycast AI を再起動すること

Q: ウォーターマークを無効にするにはどうすればいいですか?

A: .env ファイルで以下の設定を行ってください。

SEEDREAM_DEFAULT_WATERMARK=false

Q: 画像はどこに保存されますか?

A: デフォルトでは ./seedream_images/ ディレクトリに日付と機能別に分類されて保存されます。

seedream_images/
├── 2025-11-18/
│   ├── text_to_image/
│   ├── image_to_image/
│   └── multi_image_fusion/

Q: プロンプトテンプレートを使用するにはどうすればいいですか?

A: テンプレート名 + キーワードを直接入力するだけです。

潮流パーティー、キーワード: コカ・コーラ
ブログ記事の表紙、テーマ: AI 技術革新
国潮スタイル、テーマ: 中秋節

貢献

コードの貢献、問題の報告、または提案を歓迎します！

貢献方法

1. このリポジトリをフォークします。
2. 新しい機能ブランチを作成します (git checkout -b feature/AmazingFeature)。
3. 変更をコミットします (git commit -m 'Add some AmazingFeature')。
4. ブランチにプッシュします (git push origin feature/AmazingFeature)。
5. プルリクエストを作成します。

開発ガイド

• 既存のコードスタイルに従ってください。
• 必要なテストを追加してください。
• 関連するドキュメントを更新してください。
• すべてのテストが通過することを確認してください。

謝辞

• tengmmvp/Seedream_MCP の原作者に感謝します。
• 火山エンジンが提供する Seedream 4.0 API に感謝します。
• 七牛雲が提供するクラウドストレージサービスに感謝します。

📄 ライセンス

このプロジェクトは MIT ライセンスの下で公開されています。詳細は LICENSE ファイルを参照してください。

連絡先

• GitHub Issues: https://github.com/joeseesun/Seedream_MCP/issues
• 原プロジェクト: https://github.com/tengmmvp/Seedream_MCP

⭐ このプロジェクトが役に立った場合は、スターをつけていただけると幸いです！