Seedream MCP

🚀 MCP Doubao Seedream 4.0 - 豆包画像生成MCPサーバー

このサーバーは、Model Context Protocol (MCP) をベースにした豆包 Seedream 4.0 モデルの文章から画像を生成するサーバーで、Claude Code に直接統合して使用することができます。

✨ 主な機能

• 🎨 AI画像生成：豆包 Seedream モデルに基づく文章から画像を生成する機能
• 📁 自動ダウンロード：生成された画像が指定されたディレクトリに自動的にダウンロードされます
• 🔧 柔軟な設定：様々なサイズ、透かしの制御、バッチ生成をサポートします
• 🚀 即時使用可能：MCP プロトコルを通じて Claude Code にシームレスに統合できます
• 💾 ローカル保存：画像はローカルに保存され、後で使用するのに便利です

🚀 クイックスタート

1. 環境要件

• Python 3.11 以上
• uv（推奨）または pip
• Claude Code

2. インストール

# プロジェクトをクローンする
git clone <your-repo-url>
cd seedream_mcp

# 方法1：uvを使用する（推奨）
uv sync

# 方法2：pipを使用する
pip install -r requirements.txt

注意：requirements.txt は以下のコマンドで生成されます。

uv export --format requirements.txt --output-file requirements.txt

3. 設定

ARK_API_KEY は、火山方舟コンソール(https://www.volcengine.com/product/ark)から取得できます。

豆包 API キーの環境変数を設定します。

export ARK_API_KEY="your-api-key-here"

または、Claude Code の設定で設定します。

{
  "mcpServers": {
    "mcp-doubao": {
      "command": "uv",
      "args": ["run", "python", "-m", "mcp_doubao.server"],
      "cwd": "/path/to/your/seedream_mcp",
      "env": {
        "ARK_API_KEY": "your-api-key-here"
      }
    }
  }
}

4. テスト実行

# サーバーをテストする
uv run python -m mcp_doubao.server

# 画像生成をテストする（オプション）
uv run python -c "
import asyncio
import sys
sys.path.append('src')
from mcp_doubao.tools import handle_generate_images

async def test():
    result = await handle_generate_images({
        'prompt': '可愛い小猫の画像を生成して',
        'output_dir': './test_images'
    })
    print(result[0].text)

asyncio.run(test())
"

5. Claude Code への統合

詳細な統合手順は INTEGRATION_GUIDE.md を参照してください。

方法1：起動スクリプトを使用する（推奨）

プロジェクトで提供されている起動スクリプトを使用して、仮想環境と Python パスを自動的に設定します。

{
  "mcpServers": {
    "mcp-doubao": {
      "type": "stdio",
      "command": "/path/to/your/seedream_mcp/start_mcp_server.sh",
      "env": {
        "ARK_API_KEY": "your-api-key-here"
      }
    }
  }
}

方法2：uv コマンドを使用する

claude mcp add-json mcp-doubao '{
  "type": "stdio",
  "command": "uv",
  "args": ["run", "python", "-m", "mcp_doubao.server"],
  "cwd": "/path/to/your/seedream_mcp",
  "env": {
    "ARK_API_KEY": "your-api-key-here"
  }
}'

💻 使用例

基本的な使用法

Claude Code で自然言語で直接リクエストします。

桜が舞う画像を生成してください

高度な使用法

3枚の異なるスタイルの山水画を4K解像度で生成し、artworkフォルダに保存し、透かしを付けないでください

ツールパラメータ

📚 ドキュメント

プロジェクト構造

seedream_mcp/
├── src/mcp_doubao/
│   ├── __init__.py          # モジュールの初期化
│   ├── server.py            # MCPサーバーのエントリポイント
│   ├── tools.py             # ツールの定義と処理
│   ├── doubao_client.py     # 豆包APIクライアント
│   ├── downloader.py        # 画像ダウンローダー
│   ├── config.py            # 設定定数
│   └── types.py             # データ型の定義
├── start_mcp_server.sh      # Claude Codeの起動スクリプト（推奨）
├── scripts/
│   └── run_stdio.sh         # 予備の起動スクリプト
├── examples/
│   └── prompts.txt          # サンプルのプロンプト
├── tests/                   # テストファイル
├── .venv/                   # Pythonの仮想環境
├── pyproject.toml          # プロジェクトの設定
├── README.md               # プロジェクトの説明
└── INTEGRATION_GUIDE.md    # 統合ガイド

🔧 技術詳細

MCPプロトコル

Model Context Protocol 1.14.1 以上に基づいて実装され、標準化されたツールインターフェイスを提供します。

API統合

• SDK：volcengine-python-sdk[ark] 4.0.21 以上
• モデル：doubao-seedream-4-0-250828
• エンドポイント：https://ark.cn-beijing.volces.com/api/v3

画像ダウンロード

• HTTPクライアント：httpx 0.28.1 以上
• ファイル名：image_001.jpeg, image_002.jpeg...（自動的に上書きを避けます）
• 形式サポート：JPEG、PNG、WebP など
• 上書き防止：ファイルが既に存在する場合、自動的に数字のサフィックスが追加されます。

開発に関する説明

起動スクリプトの機能

start_mcp_server.sh スクリプトの特徴：

• 自動環境設定：プロジェクトの .venv 仮想環境を自動的に使用します
• パス設定：PYTHONPATH をプロジェクトの src ディレクトリに自動的に設定します
• 作業ディレクトリ：自動的にプロジェクトのルートディレクトリに切り替えます
• 環境変数：Claude Code の設定を通じて ARK_API_KEY を渡すことができます

ローカル開発

# 起動スクリプトを使用する（推奨）
./start_mcp_server.sh

# またはuvコマンドを使用する
uv run python -m mcp_doubao.server

# テストを実行する
uv run python -m pytest tests/

# コードを整形する
uv run ruff format src/

# requirements.txtを更新する（新しい依存関係を追加した後）
uv export --format requirements.txt --output-file requirements.txt

機能拡張

現在のアーキテクチャは、簡単に機能を拡張できます。

• 新しい画像パラメータ（誘導パラメータ、シードなど）を追加する
• 画像から画像を生成する機能をサポートする
• データベースの記録を追加する
• クォータ管理を追加する

トラブルシューティング

一般的な問題

1. インポートエラー：すべての依存関係が正しくインストールされていることを確認してください
2. APIエラー：ARK_API_KEY 環境変数が正しく設定されていることを確認してください
3. 権限エラー：出力ディレクトリに書き込み権限があることを確認してください
4. 画像の上書き：システムは自動的に既存の画像の上書きを避け、一意のファイル名を生成します

デバッグモード

# 詳細なログを有効にする
PYTHONPATH=src uv run python -c "
import logging
logging.basicConfig(level=logging.DEBUG)
# ... あなたのテストコード
"

依存関係

核心的な依存関係は次のとおりです。

• mcp>=1.14.1 - Model Context Protocol
• volcengine-python-sdk[ark]>=4.0.21 - 豆包 API SDK
• httpx>=0.28.1 - HTTP クライアント

📄 ライセンス

このプロジェクトは MIT ライセンスの下でオープンソース化されています。

貢献

Issue と Pull Request の投稿を歓迎します！

更新履歴

v0.1.0 (2024-09-23)

• ✨ 初期バージョンのリリース
• 🎨 基本的な画像生成機能をサポート
• 📁 画像の自動ダウンロード
• 🔧 MCP プロトコルの統合
• 💾 ローカルファイルの保存