MCP Image Generation Server

MCP 画像生成サーバー

Tencent Hunyuan、OpenAI GPT Image、Doubao API など、複数の AI プロバイダーを使用した画像生成用の Model Context Protocol（MCP）サーバーです。

バージョン：0.2.0

特長

🎯 複数の API プロバイダーに対応

• Tencent Hunyuan：中国語向けに最適化された18種類のアートスタイル
• OpenAI GPT Image：英語向けに最適化された高品質な画像生成
• Doubao（ByteDance）：12種類のスタイルに対応した品質と速度のバランス

🚀 主な機能

• テキストによる説明から画像を生成
• 複数のプロバイダーでさまざまな画像スタイルに対応
• さまざまな画像解像度に対応
• 不要な要素を除外するネガティブプロンプト
• プロバイダーの選択と管理を自動化
• プロバイダー固有のオプションを含む統一パラメーター形式

🌐 トランスポートモード（v0.2.0 の新機能）

• stdio トランスポート：IDE とのローカル連携（Cursor、Windsurf）
• HTTP トランスポート：リモートアクセスとエンタープライズデプロイ
  • 複数クライアントの同時接続
  • Bearer Token 認証
  • セッション管理
  • RESTful API エンドポイント
  • クラウドデプロイとリモートアクセスに最適

HTTP トランスポートを使用する理由 バージョン0.2.0では、以下を実現するためにStreamable HTTP（2024-11-05時点でのMCP公式標準）への対応が追加されました。

• リモートアクセス：Claude のリモート MCP には公開 HTTP エンドポイントが必要です（stdio はローカルでのみ動作します）。
• エンタープライズデプロイ：複数のクライアントが同時に利用できる、サービスの一元的なデプロイ。
• クラウドネイティブ：コンテナー、Kubernetes、ロードバランサーに対応しています。

注：これは、非推奨の SSE のみの方式ではなく、Streamable HTTP（POST/GET/DELETE）を使用します。互換性のために SSE も引き続き利用できますが、推奨標準は Streamable HTTP です。

🔧 スマートなプロバイダー管理

• 利用可能な API プロバイダーを自動検出
• 特定のプロバイダーの指定、または自動選択に対応
• 統一されたエラー処理と再試行の仕組み
• 柔軟なパラメーター形式：provider:style と provider:resolution

インストール

UV を使用する（推奨）

UV は高速でモダンな Python パッケージマネージャーです。次の方法を推奨します。

# Install UV (Windows)
curl -sSf https://astral.sh/uv/install.ps1 | powershell

# Install UV (macOS/Linux)
curl -sSf https://astral.sh/uv/install.sh | bash

# Clone the project and enter the directory
cd path/to/image-gen-mcp-server

# Create a UV virtual environment
uv venv
# Or specify an environment name
# uv venv my-env-name

# Activate the virtual environment (Windows)
.venv\Scripts\activate
# Activate the virtual environment (macOS/Linux)
source .venv/bin/activate

# Install dependencies (recommended)
uv pip install -e .

# Or use the lock file for exact versions
uv pip install -r requirements.lock.txt

従来の pip を使用する

従来の pip を使用する場合：

# Create a virtual environment
python -m venv venv
# Activate the virtual environment (Windows)
venv\Scripts\activate
# Activate the virtual environment (macOS/Linux)
source venv/bin/activate

# Install dependencies
pip install -e .
# Or use the lock file
pip install -r requirements.lock.txt

環境の設定

プロジェクトのルートに .env ファイルを作成します。利用可能なすべてのオプションについては .env.example を参照してください。

基本設定

# Image save directory
MCP_IMAGE_SAVE_DIR=./generated_images
# Public base URL for generated image links (HTTP mode, optional but recommended)
# MCP_PUBLIC_BASE_URL=https://mcp.your-domain.com
# Metadata TTL for get_image_data cache (seconds)
# MCP_IMAGE_RECORD_TTL=86400
# Max bytes allowed in get_image_data base64 response
# MCP_GET_IMAGE_DATA_MAX_BYTES=10485760

# API Provider Credentials (configure at least one)
TENCENT_SECRET_ID=your_tencent_secret_id
TENCENT_SECRET_KEY=your_tencent_secret_key
OPENAI_API_KEY=your_openai_api_key
DOUBAO_API_KEY=your_doubao_api_key
# Optional but recommended when multiple providers are configured
# MCP_DEFAULT_PROVIDER=openai

トランスポートの設定（任意）

# Transport mode: stdio (default, for local IDE) or http (for remote access)
MCP_TRANSPORT=stdio

# HTTP transport settings (only needed for HTTP mode)
MCP_HOST=127.0.0.1
MCP_PORT=8000

# Authentication (recommended for HTTP mode)
MCP_AUTH_TOKEN=your-secure-random-token

使い方

🔄 トランスポートモード

このサーバーは2つのトランスポートモードに対応しています。

機能	stdio トランスポート	HTTP トランスポート
用途	IDE とのローカル連携	リモートアクセス、エンタープライズデプロイ
接続	サブプロセス通信	HTTP/HTTPS ネットワーク
複数クライアント	❌ 単一クライアント	✅ 複数クライアントの同時接続
リモートアクセス	❌ 非対応	✅ 対応
認証	不要	Bearer Token
デプロイ	簡単	クラウド対応

🚀 クイックスタート

統合エントリーポイント（推奨）

# Method 1: Run as module (recommended)
python -m mcp_image_server

# Method 2: Use entry script
./mcp-server

# Method 3: After pip install
mcp-image-server

統合サーバーは .env ファイルで指定されたトランスポートモードを自動的に使用します。

• MCP_TRANSPORT=stdio → IDE 連携用のローカル stdio モード
• MCP_TRANSPORT=http → リモートアクセス用の HTTP サーバーモード

📡 HTTP トランスポートモード

リモートアクセスとエンタープライズデプロイには、HTTP トランスポートを使用します。

1. HTTP モードを設定する

# Set in .env file
MCP_TRANSPORT=http
MCP_HOST=127.0.0.1
MCP_PORT=8000
MCP_AUTH_TOKEN=your-secure-token  # Optional but recommended

2. HTTP サーバーを起動する

python -m mcp_image_server

サーバーは http://127.0.0.1:8000 で起動し、次のエンドポイントを提供します。

• GET /health - ヘルスチェック
• POST /mcp/v1/messages - JSON-RPC メッセージを送信
• GET /mcp/v1/messages - SSE イベントを購読
• DELETE /mcp/v1/messages - セッションを終了
• GET /images/{filename} - 生成された画像ファイルを配信

HTTP クライアントでは、generate_image ツールが images[].url を返します。
サーバーをリバースプロキシ／公開ドメイン経由で公開する場合は、URL に外部からアクセスできるよう MCP_PUBLIC_BASE_URL を設定してください。 MCP API 認証が有効な場合でもブラウザー／フロントエンドで画像を表示できるよう、/images/* は意図的に公開されています。

ベストプラクティスに沿ったエージェントのフロー：

1. generate_image を呼び出して、表示可能な画像と安定した image_id／url を取得します。
2. プログラムで扱える base64 テキストが必要な場合にのみ、get_image_data(image_id=...) を呼び出します。

3. HTTP サーバーをテストする

# Check server health
curl http://127.0.0.1:8000/health

# Run comprehensive tests
python test_mcp_server.py

# Test with API key for actual image generation
python test_mcp_server.py --with-api

4. HTTP クライアントを使用する

# Run example client
python example_http_client.py basic       # Explore server capabilities
python example_http_client.py generate    # Generate images (requires API key)

HTTP トランスポートの詳細については、HTTP_TRANSPORT_GUIDE.md を参照してください。

MCP サーバーが正常に実行されているスクリーンショット：

サーバーへの接続

MCP 対応クライアント（現在は cursor を推奨）から接続できます。サーバーは次の機能を提供します。

リソース

• styles://list - 利用可能なすべての画像スタイルを一覧表示
• resolutions://list - 利用可能なすべての画像解像度を一覧表示

ツール

• generate_image - プロンプト、スタイル、解像度に基づいて画像を生成（OpenAI は background／output_format／output_compression／moderation にも対応）
• get_image_data - image_id を指定して、以前に生成した画像の base64 テキストを取得

プロンプト

• image_generation_prompt - 画像生成プロンプトのテンプレートを作成

🎨 複数 API の使用例

基本的な使用方法

# Auto-select best available provider
generate_image(prompt="A cute cat in a garden")

# Specify a particular provider
generate_image(prompt="A cute cat", provider="openai")
generate_image(prompt="一只可爱的小猫", provider="hunyuan")
generate_image(prompt="Cute kitten", provider="doubao")

高度なパラメーターの使用方法

# Use provider-specific styles and resolutions
generate_image(
    prompt="Cyberpunk city skyline", 
    style="hunyuan:saibopengke", 
    resolution="hunyuan:1024:768"
)

# Mix provider selection with standard parameters
generate_image(
    prompt="Fantasy magical forest",
    provider="doubao",
    style="fantasy",
    resolution="1024x768",
    negative_prompt="low quality, blurry"
)

# OpenAI with high-resolution output
generate_image(
    prompt="Artistic portrait of a musician",
    provider="openai",
    style="artistic",
    resolution="1536x1024"
)

📊 対応プロバイダーとパラメーター

Tencent Hunyuan

• スタイル：riman、xieshi、shuimo、saibopengke、youhua など、18 種類の選択肢
• 解像度：768:768 から 1280:720 まで、8 種類の選択肢
• 特長：中国語に最適化され、豊かな芸術スタイルに対応

OpenAI GPT Image

• スタイル：natural、vivid、realistic、artistic、anime など、12 種類の選択肢
• 解像度：1024x1024、1536x1024、1024x1536、auto の 4 種類
• 高度なオプション：background、output_format、output_compression、moderation（MCP クライアント経由）
• 特長：高品質な出力、英語に最適化

Doubao（ByteDance）

• スタイル：general、anime、chinese_painting、cyberpunk など、12 種類の選択肢
• 解像度：モデルに依存（設定済みモデル／フォールバックモデルによって自動検証）
• 特長：品質と速度のバランス

Cursor との統合

統合の設定手順と設定 JSON の例については、次を参照してください。

• docs/VSCODE_INTEGRATION.md

最低限必要な環境変数：

• MCP_IMAGE_SAVE_DIR
• 実際に使用するプロバイダーの認証情報： TENCENT_SECRET_ID + TENCENT_SECRET_KEY、OPENAI_API_KEY、DOUBAO_API_KEY

任意のプロバイダー／モデル制御：

• OPENAI_BASE_URL、OPENAI_MODEL
• DOUBAO_ENDPOINT、DOUBAO_MODEL、DOUBAO_FALLBACK_MODEL
• MCP_DEFAULT_PROVIDER（複数のプロバイダーを有効にする場合に推奨）

実行中に .env のモデル／デフォルトプロバイダーの値を変更した後は、reload_config を呼び出してください。

🧪 テスト

このプロジェクトには、包括的なテストツールが含まれています。

プロトコルテスト（API キー不要）

# Test MCP protocol functionality without API keys
python test_mcp_server.py

次の項目をテストします。

• ✅ ヘルスチェックエンドポイント
• ✅ MCP 初期化ハンドシェイク
• ✅ ツール一覧表示
• ✅ リソースの一覧表示と読み取り
• ✅ プロンプト一覧表示
• ✅ セッション管理

機能テスト（API キーが必要）

# Test actual image generation with configured providers
python test_mcp_server.py --with-api

さらに次の項目をテストします。

• ✅ OpenAI による実際の画像生成
• ✅ Hunyuan による実際の画像生成
• ✅ Doubao による実際の画像生成

注：機能テストを実行するには、少なくとも 1 つの API キーを .env に設定する必要があります。

トラブルシューティング

一般的な問題

• 環境変数が正しく設定されていることを確認してください
• パスにスペースが含まれていないか確認し、必要に応じて引用符を使用してください
• 仮想環境を使用している場合は、仮想環境が有効になっていることを確認してください
• サーバースクリプトを直接実行して、エラーがないか確認してください
• uv --version で UV 環境を確認してください

HTTP トランスポートの問題

• 接続拒否：サーバーが正しいホスト／ポートで実行されていることを確認してください
• 401 Unauthorized：MCP_AUTH_TOKEN の設定を確認してください
• 404 Session not found：接続を再初期化して、新しいセッション ID を取得してください
• 利用可能なプロバイダーがありません：.env で少なくとも 1 つの API プロバイダーを設定してください

詳細なトラブルシューティングについては、HTTP_TRANSPORT_GUIDE.md を参照してください。

フロントエンドデモ

フロントエンド統合の例については、web-design-demo/ を参照してください。 この例では、Cursor IDE を使用して実際のプロジェクトを開発する方法を示しています。開発環境から直接、MCP ツール 🛠️ を使って画像を生成、管理できます。画像生成ツールを切り替えたり、IDE を離れたりする必要はありません。開発ワークフローの中ですべて完結できます ✨。

• デモ Web サイトのスクリーンショット

API リファレンス

マルチ API アーキテクチャ

このプロジェクトでは、統一されたインターフェースを通じて複数の画像生成 API を利用できるようになりました。

対応 API

1. Tencent Hunyuan 画像生成 API（オリジナル）
2. OpenAI GPT Image API（新規）
3. Doubao 画像生成 API（新規）

統合 MCP リソース

• providers://list - 利用可能なすべてのプロバイダーを一覧表示します
• styles://list - すべてのプロバイダーのスタイルを一覧表示します
• resolutions://list - すべてのプロバイダーの解像度を一覧表示します
• styles://provider/{provider_name} - 指定したプロバイダーのスタイルを取得します
• resolutions://provider/{provider_name} - 指定したプロバイダーの解像度を取得します

拡張 MCP ツール

• generate_image - インテリジェントなルーティングによるマルチプロバイダー画像生成
• get_image_data - 生成された画像の ID を指定して、Base64 テキストデータを取得します
• reload_config - プロセスを再起動せずに、実行時の設定／モデルを env／.env から再読み込みします（安全な対象範囲のみ）

Tencent Hunyuan 画像生成 API

このプロジェクトでは当初から Tencent Hunyuan 画像生成 API を使用しており、現在もサポートしています。主な仕様は次のとおりです。

API エンドポイント

• ドメイン：hunyuan.tencentcloudapi.com
• リージョン：ap-guangzhou（現在は広州リージョンのみ対応）
• デフォルトの API レート制限：毎秒 20 リクエスト
• 同時実行タスク数：デフォルトでは一度に 1 タスク

タスクの流れ

1. タスクの送信：テキストの説明を添えて、非同期画像生成タスクを送信します
2. タスクの照会：タスク ID を使用して、タスクのステータスと結果を取得します
3. 結果 URL：生成された画像 URL の有効期間は 1 時間です

API の詳細なドキュメントと料金については、以下を参照してください。

• API ドキュメント
• 料金の詳細

OpenAI GPT Image API

API の機能

• 高品質な画像生成
• プロンプトの自動最適化
• 複数のスタイルオプション
• 高解像度出力への対応

Doubao API（ByteDance）

API の機能

• ByteDance 独自の画像生成モデル
• 品質と速度のバランス
• 中国語と英語のプロンプトに対応
• 多様なアートスタイル

ロードマップ

• Version 0.2.0（現在）

  • ✅ Tencent Hunyuan の画像生成 API
  • ✅ OpenAI GPT Image API との統合
  • ✅ Doubao API との統合
  • ✅ マルチプロバイダー管理システム
  • ✅ インテリジェントなプロバイダー選択
  • ✅ 統一されたパラメーターインターフェース
  • ✅ Streamable HTTP プロトコルを使用した HTTP トランスポート
  • ✅ リモートアクセスのサポート
  • ✅ 複数クライアントの同時接続
  • ✅ Bearer Token 認証
  • ✅ セッション管理
  • ✅ 包括的なテストスイート

• 今後の予定

  • 以下を含む、より多くの主流のテキストから画像を生成するモデルの API をサポートします。
    • Qwen-Image（Qwen/Wan ファミリー）
    • オープンソースモデルの API サービス（例：FLUX、SDXL/SD3.5）
  • 高度な機能：
    • 画像の編集と変更
    • 画像の一括生成
    • スタイル変換機能
    • カスタムモデルのファインチューニングのサポート
  • MCP との連携強化：
    • リアルタイムの生成進捗
    • 画像の履歴と管理
    • 高度なプロンプトテンプレート

より多くのモデルの統合や新機能に向けた、コミュニティからの貢献を歓迎します！

互換性

• stdio：Cursor および Windsurf で動作を確認済みです。
• HTTP（Streamable HTTP）：HTTP トランスポートをサポートする MCP クライアントで動作します。
• その他のクライアントや環境との互換性は、クライアント側の MCP 実装によって異なります。

コントリビューション

あらゆる種類のコントリビューションを歓迎します！ご協力いただける方法を以下に示します。

• 🐛 バグや問題を報告する
• 💡 新機能や改善を提案する
• 🔧 プルリクエストを送信する
• 🎨 さらに多くの画像生成モデルへの対応を追加する

コントリビューションを始める

1. リポジトリをフォークする
2. 機能ブランチを作成する（git checkout -b feature/AmazingFeature）
3. 変更をコミットする（git commit -m 'feat: add some AmazingFeature'）
4. ブランチにプッシュする（git push origin feature/AmazingFeature）
5. プルリクエストを作成する

適宜テストを更新し、既存のコーディングスタイルに従ってください。

このプロジェクトをより良くすることに関心をお寄せいただき、ありがとうございます！