mcpField
I
Image Generation MCP Server

Image Generation MCP Server

ローカル
pvliesdonk.github.ioメディア・デザイン16 週間前に更新
リポジトリ公式サイト

Image Generation MCP Server について

Image Generation MCPは、OpenAI、Google Gemini、Stable Diffusion WebUI、またはプレースホルダーを通じて画像を生成・変換するMCPサーバーです。ClaudeなどのMCPクライアント向けに、モデル情報に基づく選択機能と画像閲覧ツールを提供します。

主な機能

  1. 01複数の画像プロバイダーで画像を生成
  2. 02プロンプトのキーワードからプロバイダーを自動選択
  3. 03生成画像のサイズ、形式、範囲を変更
  4. 04時間のかかるStable Diffusionタスクをバックグラウンド実行
  5. 05MCP Appsギャラリーで画像を閲覧・編集
  6. 06スタイルライブラリーに再利用可能なスタイルを保存

活用シーン

  1. 01指定したプロバイダーでプロンプトから画像を生成
  2. 02プレースホルダーでドラフト画像を作成
  3. 03再生成せずに画像をトリミングまたは拡大縮小
  4. 04ギャラリーで最近生成した画像を確認

MCP 対応

MCPクライアントに画像生成・変換機能と画像リソースを提供し、対応クライアントではMCP Appsギャラリーも利用できます。stdioとStreamable HTTPのトランスポートに対応します。

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定
{
  "mcpServers": {
    "pvliesdonk-image-generation": {
      "command": "uvx",
      "args": [
        "image-generation-mcp"
      ],
      "env": {
        "IMAGE_GENERATION_MCP_KV_STORE_URL": "<IMAGE_GENERATION_MCP_KV_STORE_URL>",
        "IMAGE_GENERATION_MCP_TOOLS_ALLOW": "<IMAGE_GENERATION_MCP_TOOLS_ALLOW>",
        "IMAGE_GENERATION_MCP_TOOLS_DENY": "<IMAGE_GENERATION_MCP_TOOLS_DENY>",
        "IMAGE_GENERATION_MCP_SERVER_NAME": "<IMAGE_GENERATION_MCP_SERVER_NAME>",
        "IMAGE_GENERATION_MCP_INSTRUCTIONS": "<IMAGE_GENERATION_MCP_INSTRUCTIONS>",
        "FASTMCP_LOG_LEVEL": "<FASTMCP_LOG_LEVEL>",
        "FASTMCP_ENABLE_RICH_LOGGING": "<FASTMCP_ENABLE_RICH_LOGGING>",
        "IMAGE_GENERATION_MCP_A1111_HOST": "<IMAGE_GENERATION_MCP_A1111_HOST>",
        "IMAGE_GENERATION_MCP_A1111_MODEL": "<IMAGE_GENERATION_MCP_A1111_MODEL>",
        "IMAGE_GENERATION_MCP_READ_ONLY": "<IMAGE_GENERATION_MCP_READ_ONLY>",
        "IMAGE_GENERATION_MCP_SCRATCH_DIR": "<IMAGE_GENERATION_MCP_SCRATCH_DIR>",
        "IMAGE_GENERATION_MCP_OPENAI_API_KEY": "<IMAGE_GENERATION_MCP_OPENAI_API_KEY>",
        "IMAGE_GENERATION_MCP_GOOGLE_API_KEY": "<IMAGE_GENERATION_MCP_GOOGLE_API_KEY>",
        "IMAGE_GENERATION_MCP_SD_WEBUI_HOST": "<IMAGE_GENERATION_MCP_SD_WEBUI_HOST>",
        "IMAGE_GENERATION_MCP_SD_WEBUI_MODEL": "<IMAGE_GENERATION_MCP_SD_WEBUI_MODEL>",
        "IMAGE_GENERATION_MCP_DEFAULT_PROVIDER": "<IMAGE_GENERATION_MCP_DEFAULT_PROVIDER>",
        "IMAGE_GENERATION_MCP_TRANSFORM_CACHE_SIZE": "<IMAGE_GENERATION_MCP_TRANSFORM_CACHE_SIZE>",
        "IMAGE_GENERATION_MCP_PAID_PROVIDERS": "<IMAGE_GENERATION_MCP_PAID_PROVIDERS>",
        "IMAGE_GENERATION_MCP_STYLES_DIR": "<IMAGE_GENERATION_MCP_STYLES_DIR>",
        "IMAGE_GENERATION_MCP_ALLOW_LOCAL_FILE_INPUT": "<IMAGE_GENERATION_MCP_ALLOW_LOCAL_FILE_INPUT>",
        "IMAGE_GENERATION_MCP_MAX_INPUT_IMAGE_BYTES": "<IMAGE_GENERATION_MCP_MAX_INPUT_IMAGE_BYTES>",
        "IMAGE_GENERATION_MCP_FETCH_TIMEOUT_S": "<IMAGE_GENERATION_MCP_FETCH_TIMEOUT_S>",
        "IMAGE_GENERATION_MCP_TRANSFER_TTL_DEFAULT_S": "<IMAGE_GENERATION_MCP_TRANSFER_TTL_DEFAULT_S>",
        "IMAGE_GENERATION_MCP_TRANSFER_TTL_MAX_S": "<IMAGE_GENERATION_MCP_TRANSFER_TTL_MAX_S>",
        "IMAGE_GENERATION_MCP_TRANSFER_GRACE_TTL_S": "<IMAGE_GENERATION_MCP_TRANSFER_GRACE_TTL_S>",
        "IMAGE_GENERATION_MCP_TRANSFER_LEASE_S": "<IMAGE_GENERATION_MCP_TRANSFER_LEASE_S>",
        "IMAGE_GENERATION_MCP_TRANSFER_MAX_UPLOAD_BYTES": "<IMAGE_GENERATION_MCP_TRANSFER_MAX_UPLOAD_BYTES>",
        "IMAGE_GENERATION_MCP_BASE_URL": "<IMAGE_GENERATION_MCP_BASE_URL>",
        "IMAGE_GENERATION_MCP_BEARER_TOKEN": "<IMAGE_GENERATION_MCP_BEARER_TOKEN>",
        "IMAGE_GENERATION_MCP_OIDC_CONFIG_URL": "<IMAGE_GENERATION_MCP_OIDC_CONFIG_URL>",
        "IMAGE_GENERATION_MCP_OIDC_CLIENT_ID": "<IMAGE_GENERATION_MCP_OIDC_CLIENT_ID>",
        "IMAGE_GENERATION_MCP_OIDC_CLIENT_SECRET": "<IMAGE_GENERATION_MCP_OIDC_CLIENT_SECRET>",
        "IMAGE_GENERATION_MCP_OIDC_AUDIENCE": "<IMAGE_GENERATION_MCP_OIDC_AUDIENCE>",
        "IMAGE_GENERATION_MCP_OIDC_REQUIRED_SCOPES": "<IMAGE_GENERATION_MCP_OIDC_REQUIRED_SCOPES>",
        "IMAGE_GENERATION_MCP_OIDC_ADVERTISED_SCOPES": "<IMAGE_GENERATION_MCP_OIDC_ADVERTISED_SCOPES>",
        "IMAGE_GENERATION_MCP_OIDC_JWT_SIGNING_KEY": "<IMAGE_GENERATION_MCP_OIDC_JWT_SIGNING_KEY>",
        "IMAGE_GENERATION_MCP_OIDC_VERIFY_ACCESS_TOKEN": "<IMAGE_GENERATION_MCP_OIDC_VERIFY_ACCESS_TOKEN>",
        "IMAGE_GENERATION_MCP_APP_DOMAIN": "<IMAGE_GENERATION_MCP_APP_DOMAIN>",
        "IMAGE_GENERATION_MCP_AUTH_MODE": "<IMAGE_GENERATION_MCP_AUTH_MODE>",
        "IMAGE_GENERATION_MCP_BEARER_TOKENS_FILE": "<IMAGE_GENERATION_MCP_BEARER_TOKENS_FILE>",
        "IMAGE_GENERATION_MCP_BEARER_DEFAULT_SUBJECT": "<IMAGE_GENERATION_MCP_BEARER_DEFAULT_SUBJECT>",
        "IMAGE_GENERATION_MCP_HTTP_PATH": "<IMAGE_GENERATION_MCP_HTTP_PATH>",
        "PUID": "<PUID>",
        "PGID": "<PGID>"
      }
    }
  }
}
起動コマンドuvx image-generation-mcp
設定が必要な環境変数
IMAGE_GENERATION_MCP_KV_STORE_URLPersistent-state backend URL shared by every pvl-core subsystem that needs state. `memory://` is in-process and lost on restart; `file:///path` persists on one server; `redis://`, `dynamodb://` and `mongodb://` each need their matching extra. When unset, defaults to `file:///data/state` (the volume family Docker images mount), or to `memory://` — with a warning — on a host where that directory is not usable.
IMAGE_GENERATION_MCP_TOOLS_ALLOWComma-separated explicit tool names this instance exposes; every other tool is hidden from listings and cannot be invoked. Names matching no registered tool are inert. Mutually exclusive with `tools_deny`. Takes effect through `apply_tool_visibility`.
IMAGE_GENERATION_MCP_TOOLS_DENYComma-separated explicit tool names hidden from this instance (absent from listings, cannot be invoked). Names matching no registered tool are inert. Mutually exclusive with `tools_allow`. Takes effect through `apply_tool_visibility`.
IMAGE_GENERATION_MCP_SERVER_NAMERename this server instance; defaults to the project name.
IMAGE_GENERATION_MCP_INSTRUCTIONSReplaces the default MCP instructions text sent to clients.
FASTMCP_LOG_LEVELLog level for FastMCP internals and app loggers (DEBUG / INFO / WARNING / ERROR / CRITICAL). The -v CLI flag overrides to DEBUG.
FASTMCP_ENABLE_RICH_LOGGINGSet false for plain or structured JSON log output.
IMAGE_GENERATION_MCP_A1111_HOSTDeprecated alias for IMAGE_GENERATION_MCP_SD_WEBUI_HOST; logs a warning when used.
IMAGE_GENERATION_MCP_A1111_MODELDeprecated alias for IMAGE_GENERATION_MCP_SD_WEBUI_MODEL; logs a warning when used.
IMAGE_GENERATION_MCP_READ_ONLYWhen true, write-tagged tools (image generation, transforms, uploads) are hidden from clients. Set false to enable them.
IMAGE_GENERATION_MCP_SCRATCH_DIRDirectory where generated images are saved. Created automatically on first use.
IMAGE_GENERATION_MCP_OPENAI_API_KEYシークレットOpenAI API key. Enables the OpenAI provider (gpt-image-2, gpt-image-1.5, dall-e-3) when set.
IMAGE_GENERATION_MCP_GOOGLE_API_KEYシークレットGoogle API key. Enables the Gemini provider (gemini-3.1-flash-image and others) when set. Get a key at https://aistudio.google.com/apikey.
IMAGE_GENERATION_MCP_SD_WEBUI_HOSTSD WebUI base URL (such as http://localhost:7860). Enables the SD WebUI provider when set. Compatible with AUTOMATIC1111, Forge, reForge, and Forge-neo.
IMAGE_GENERATION_MCP_SD_WEBUI_MODELSD WebUI checkpoint name, used for model-aware preset detection (SD 1.5 / SDXL / Lightning) and checkpoint override. Unset uses the instance's current model.
IMAGE_GENERATION_MCP_DEFAULT_PROVIDERProvider used when no keyword triggers auto-selection: auto, openai, gemini, sd_webui, or placeholder. auto picks the first configured provider.
IMAGE_GENERATION_MCP_TRANSFORM_CACHE_SIZEMaximum number of transformed image results (resize, crop, convert) kept in memory. Set 0 to disable caching.
IMAGE_GENERATION_MCP_PAID_PROVIDERSComma-separated provider names that cost money; generate_image asks for confirmation (client elicitation) before using them. An empty value falls back to this default; to disable confirmation, set a value that names no provider (such as none).
IMAGE_GENERATION_MCP_STYLES_DIRDirectory for style preset files (Markdown with YAML front matter). Created automatically if it does not exist.
IMAGE_GENERATION_MCP_ALLOW_LOCAL_FILE_INPUTAllow reading input images from local filesystem paths. Off by default: only URLs and uploads are accepted.
IMAGE_GENERATION_MCP_MAX_INPUT_IMAGE_BYTESMaximum accepted input image size in bytes.
IMAGE_GENERATION_MCP_FETCH_TIMEOUT_SHTTP timeout in seconds when fetching remote image URLs (fetch_image and URL inputs).
IMAGE_GENERATION_MCP_TRANSFER_TTL_DEFAULT_SLink lifetime in seconds when the caller requests no explicit TTL.
IMAGE_GENERATION_MCP_TRANSFER_TTL_MAX_SCeiling in seconds a caller-requested link TTL is clamped to.
IMAGE_GENERATION_MCP_TRANSFER_GRACE_TTL_SPost-success grace window in seconds: a served token's TTL shrinks to this so a stalled transfer can retry within it.
IMAGE_GENERATION_MCP_TRANSFER_LEASE_SCrashed-handler reclaim window in seconds for an in-flight reservation.
IMAGE_GENERATION_MCP_TRANSFER_MAX_UPLOAD_BYTESMaximum size in bytes of a single upload.
IMAGE_GENERATION_MCP_BASE_URLPublic base URL of the deployed server, e.g. `https://mcp.example.com`. Required for OIDC. Also the fallback source of the MCP Apps domain when `app_domain` is unset.
IMAGE_GENERATION_MCP_BEARER_TOKENシークレットSingle shared bearer token; enables bearer auth unless `bearer_tokens_file` is set, which takes precedence.
IMAGE_GENERATION_MCP_OIDC_CONFIG_URLOIDC discovery document URL, e.g. `https://auth.example.com/.well-known/openid-configuration`.
IMAGE_GENERATION_MCP_OIDC_CLIENT_IDOIDC client identifier registered with the provider.
IMAGE_GENERATION_MCP_OIDC_CLIENT_SECRETシークレットOIDC client secret registered with the provider.
IMAGE_GENERATION_MCP_OIDC_AUDIENCEExpected `aud` claim; tokens issued for another audience are rejected.
IMAGE_GENERATION_MCP_OIDC_REQUIRED_SCOPESScopes a caller must present, space- or comma-separated. Defaults to `openid` in oidc-proxy mode.
IMAGE_GENERATION_MCP_OIDC_ADVERTISED_SCOPESScopes advertised to MCP clients in protected-resource metadata, space- or comma-separated. Overrides the default `openid offline_access`; `oidc_required_scopes` is always added on top. Set this when the registered client is not permitted `offline_access`, or to have clients request extra claim scopes (e.g. `groups`) without also requiring them in every token.
IMAGE_GENERATION_MCP_OIDC_JWT_SIGNING_KEYシークレットSigning key for issued JWTs; used in oidc-proxy mode only. When unset, the key is derived deterministically from `oidc_client_secret`, so tokens survive a restart — but rotating that secret invalidates every issued token. Set this explicitly to decouple token validity from secret rotation. Generate with `openssl rand -hex 32`.
IMAGE_GENERATION_MCP_OIDC_VERIFY_ACCESS_TOKENシークレットValidate the access token instead of the id token.
IMAGE_GENERATION_MCP_APP_DOMAINMCP Apps iframe domain, used for CSP sandboxing. Overrides the host derived from `base_url`.
IMAGE_GENERATION_MCP_AUTH_MODEシークレットExplicit auth-mode override, accepting `remote` or `oidc-proxy` (case- and whitespace-insensitive). When unset the mode is auto-detected from which auth variables are set; the override exists because having all four OIDC variables set is ambiguous between those two modes. Other values are ignored with a warning.
IMAGE_GENERATION_MCP_BEARER_TOKENS_FILEシークレットPath to a TOML file mapping bearer tokens to subjects; overrides the single-token `bearer_token` mode.
IMAGE_GENERATION_MCP_BEARER_DEFAULT_SUBJECTSubject assigned to the single-token bearer mode; ignored when `bearer_tokens_file` is set, since mapped mode carries per-token subjects.
IMAGE_GENERATION_MCP_HTTP_PATHMount path for the MCP endpoint.
PUIDRun the server process as this UID; the container entrypoint chowns writable paths to match.
PGIDRun the server process as this GID; pair with PUID to match the owner of a mounted volume.

ローカルサーバーにはマシン上の実行環境（Node.js 18 以上など）が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ
pypiimage-generation-mcp1.12.1
ocighcr.io/pvliesdonk/image-generation-mcp:v1.12.1

ツール

ツール一覧はまだ取得されていません

ローカルサーバーのツールはマシン上で起動して初めて取得できます。メンテナーはまだツール一覧を提供していません。

詳細

画像生成 MCP

CI codecov PyPI Python License Docker Docs llms.txt Template

FastMCP を基盤とする、複数プロバイダー対応の画像生成 MCP サーバーです。OpenAI、Google Gemini、Stable Diffusion（SD WebUI）、または無料のプレースホルダープロバイダーを使い、Claude Desktop、Claude Code、または任意の MCP クライアントから画像を生成できます。

ドキュメント | 設定ウィザード | PyPI | Docker

主な機能

  • 複数プロバイダー対応：OpenAI（gpt-image-2、gpt-image-1.5、dall-e-3）、Google Gemini（gemini-3.1-flash-image、gemini-3-pro-image、gemini-3.1-flash-lite-image）、SD WebUI（Stable Diffusion / Forge / reForge）、およびテスト用の無料プレースホルダーに対応しています。
  • モデルごとのスタイルメタデータ：すべてのモデルに style_profile（強み、プロンプトの文法、ライフサイクル）が設定されています。list_providers には、非推奨モデルを示すトップレベルの warnings 配列が含まれます。モデルカタログをご覧ください。
  • キーワードに基づく自動選択：provider="auto" はプロンプトの内容に応じて振り分けます（テキスト／ロゴ → OpenAI、フォトリアル／アニメ → SD WebUI、ドラフト → プレースホルダー）。
  • CDN スタイルの画像変換：image://{id}/view?format=webp&width=512&crop_x=... を使い、再生成することなく、必要に応じてサイズ変更、再エンコード、トリミングを行います。
  • ハイブリッドバックグラウンドタスク：時間のかかる SD 生成は task=True で実行して状態をポーリングします。短時間の OpenAI 呼び出しでは、フォアグラウンドで進行状況がストリーミングされます。
  • MCP Apps ギャラリー＋ビューアー：app: リソースに対応したクライアント向けに、生成した画像の閲覧、編集、トリミング、回転ができるインタラクティブ UI を提供します。
  • 本番環境へのデプロイ：Docker（マルチアーキテクチャ）、強化された systemd を備えた .deb／.rpm、OIDC とベアラ認証、HTTP セッションの再開に対応する永続的な EventStore をサポートします。

このサーバーでできること

このサーバーをMCPクライアントにマウントすると、次のように依頼できます。

  • 「使い込まれたオーク材のテーブルに置かれたコーヒーマグの商品写真を、16:9で、文字なしで生成してください。」 gpt-image-1.5 に振り分け、文字表現に対応したフォトリアリズムを実現します。
  • 「夕暮れ時のサイバーパンクな路地のコンセプトアートを、3種類のバリエーションで作成してください。」 provider="sd_webui" を指定した generate_image と、dreamshaperXL のようなスタイライズされたチェックポイントを組み合わせます。
  • 「この画像を被写体が中央にくるように1:1の正方形にトリミングし、512pxにリサイズしてください。」 image://{id}/view?width=512&height=512&crop_x=... のリソース変換を使用します。
  • 「最近生成した画像を見せてください。」 image://list リソースとMCP Appsギャラリービューアーを使って、ギャラリーを表示します。
  • 「今後のリクエストに適用できるように、このスタイルを「cyberpunk-night」として保存してください。」 スタイルライブラリを使用します。スタイルライブラリのMarkdownブリーフは、LLMがプロバイダーごとに解釈します。
  • 「最後に撮影した写真の背景を、夕焼け空に置き換えてください。」 ギャラリーの image_id を参照として指定した transform_image を使用します（Geminiによる画像から画像への変換）。

インストール

PyPIから
pip install image-generation-mcp

pyproject.toml の PROJECT-EXTRAS-START / PROJECT-EXTRAS-END センチネルを使ってオプションの追加パッケージを追加する場合は、以下に記載してください。

追加パッケージ含まれるもの使用する場面
mcpfastmcp[tasks]>=3.0,<4バックグラウンドタスクのサポート（task=True）。長時間かかるSD生成に必要です。
openaiopenai>=1.0OpenAIプロバイダーを有効にします。
google-genaigoogle-genai>=1.0Geminiプロバイダーを有効にします。
allfastmcp[tasks] + openai + google-genaiSD WebUI以外のすべて（SD WebUIはHTTPのみを使用するため、追加パッケージは不要です）。

例：pip install image-generation-mcp[all]。

ソースから
git clone https://github.com/pvliesdonk/image-generation-mcp.git
cd image-generation-mcp
uv sync --all-extras --all-groups
Docker
docker pull ghcr.io/pvliesdonk/image-generation-mcp:latest

最新のリリースではなく、マージ済みの最新コードを実行するには、ローリングタグの edge を使用してください。このタグは main へのマージのたびに再ビルドされ、バージョン情報は付与されません。タグの一覧はイメージタグを参照してください。

docker pull ghcr.io/pvliesdonk/image-generation-mcp:edge

リポジトリのルートには、出発点として compose.yml が用意されています。.env.example を .env にコピーして編集し、docker compose up -d を実行してください。

リモートPythonデバッガーを接続する方法（開発時のみ。プロトコルは認証されません）については、リモートデバッグを参照してください。

Linuxパッケージ（.deb / .rpm）

GitHub Releasesページから .deb または .rpm パッケージをダウンロードしてください。どちらもセキュリティ強化済みのsystemdユニットをインストールします。環境設定は /etc/image-generation-mcp/env から読み込まれます（同梱の /etc/image-generation-mcp/env.example をコピーしてください）。

Claude Desktop（.mcpbバンドル）

GitHub Releasesページから .mcpb バンドルをダウンロードし、ダブルクリックしてインストールするか、次を実行してください。

mcpb install image-generation-mcp-<version>.mcpb

Claude DesktopではGUIウィザードで必要な環境変数を尋ねられるため、JSONを手動で編集する必要はありません。

Claude Desktopの手動設定やセットアップ方法については、Claude Desktopのデプロイを参照してください。

リリースチャンネル

成果物は3つのチャンネルで公開されます。各行に、そのチャンネルで公開されるものをすべて記載しています。

チャンネルバージョンの識別情報成果物
edge（ローリング）なし。コミットが識別情報になりますマージのたびに再ビルドされる Docker イメージ :edge；ワークフロー成果物 mcpb-bundle-edge としての .mcpb バンドル；成果物 plugin-zip-edge としての Claude Code プラグイン .zip；ローリングする unstable ドキュメントバージョン。git タグ、GitHub リリース、PyPI エントリーは作成されません。
プレリリースリリースプルリクエストで計算・レビューされる vX.Y.Z-rc.NPyPI（プレリリース版 X.Y.ZrcN として）；ホイール、sdist、.deb／.rpm パッケージ、.mcpb バンドル、プラグイン .zip、SBOM を添付した GitHub リリース；変更されない vX.Y.Z-rc.N タグと、順序を考慮するローリング rc タグでの Docker イメージ。プラグインマーケットプレイス、MCP レジストリ、ドキュメントのデプロイはスキップされます。
安定版vX.Y.Zすべて：PyPI、Docker（バージョンタグと、順序を考慮する latest／vX／vX.Y）、.deb／.rpm、GitHub リリースアセット（ホイール、sdist、.mcpb バンドル、プラグイン .zip、SBOM）、プラグインマーケットプレイスと MCP レジストリのエントリー（リリースが最新の安定版の場合）、順序を考慮する latest エイリアス付きのバージョン別ドキュメント。

プレリリースは PyPI に公開されるため、候補版の .mcpb バンドルをインストールできます。このバンドルはコードを含まず、PyPI を参照します。通常のインストーラーには表示されません。PEP 440 のリゾルバーは、要件でプレリリースを指定するか、--pre を渡さない限り、プレリリースをスキップするためです。pip install image-generation-mcp==X.Y.ZrcN で候補版を名前指定してインストールします。PyPI では PEP 440 の正規形式で表記されますが、タグでは SemVer を使用します。ローリングポインターは順序を考慮するため、古い release/X.Y ブランチからパッチリリースを作成しても、latest 系タグが古い内容に戻ることはありません。また、すでにリリース済みのバージョンの候補版によって rc が戻ることもありません。全体像については、リリースプロセスを参照してください。

クイックスタート

image-generation-mcp serve                                # stdio transport
image-generation-mcp serve --transport http --port 8000   # streamable HTTP

MCP トランスポートを使わずにドメインロジックを組み込むライブラリとして使用する場合は、image_generation_mcp パッケージから直接インポートしてください。エントリーポイントについては、プロジェクトの src/image_generation_mcp/ 配下にあるドメインモジュールを参照してください。

サーバー情報

サーバーは組み込みの get_server_info ツールを登録します（fastmcp_pvl_core.register_server_info_tool 経由）。これにより、運用担当者は単一の MCP 呼び出しでデプロイ済みのバージョンを確認できます。デフォルトの応答には、server_name、server_version、core_version が含まれます。リモートアップストリームと通信するサーバーでは、src/image_generation_mcp/server.py の DOMAIN-UPSTREAM-START／DOMAIN-UPSTREAM-END センチネル内にアップストリームのバージョン報告を接続します。接続パターンについては、CLAUDE.mdを参照してください。

設定

fastmcp-pvl-core ベースのすべてのサービスで共通するコア環境変数：

変数デフォルト値説明
IMAGE_GENERATION_MCP_KV_STORE_URLfile:///data/state状態を必要とするすべての pvl-core サブシステムで共有される永続状態バックエンドの URL です。memory:// はプロセス内でのみ使用され、再起動時に失われます。file:///path は1台のサーバー上に永続化されます。redis://、dynamodb://、mongodb:// には、それぞれ対応する追加パッケージが必要です。未設定の場合、Docker イメージがマウントするボリュームの場所である file:///data/state がデフォルトになります。そのディレクトリを使用できないホストでは、警告を出して memory:// がデフォルトになります。
FASTMCP_LOG_LEVELINFOFastMCP 内部とアプリのロガーのログレベルです（DEBUG／INFO／WARNING／ERROR／CRITICAL）。-v CLI フラグを指定すると DEBUG に上書きされます。
FASTMCP_ENABLE_RICH_LOGGINGtrueプレーンテキストまたは構造化 JSON 形式のログ出力にするには、false に設定します。

ドメイン固有の変数は、下記のドメイン設定に記載されています。

認証

呼び出し元は、ベアラートークンまたは OIDC（併用不可）で認証します。設定方法、複数サブジェクトにマッピングされたトークン、OIDC、トラブルシューティングについては、認証ガイドを参照してください。

スキャフォールド後のチェックリスト

copier copy と gh repo create --push の実行後：

  1. この README と CLAUDE.md の DOMAIN ブロック（DOMAIN センチネルコメントが付いた各セクション）をすべて記入します。GENERATED-ENV-TABLE-* 領域は DOMAIN ブロックではありません。設定ジェネレーターが管理し、実行のたびに書き換えます。
  2. GitHub シークレットを設定します（下記を参照）。
  3. 開発用およびドキュメント用のツールをインストールします：uv sync --all-extras --all-groups。
  4. pre-commit フックをインストールします：uv run pre-commit install。
  5. ローカルでゲートを実行します：uv run pytest -x -q && uv run ruff check --fix . && uv run ruff format . && uv run mypy src/ tests/。
  6. 最初のコミットをプッシュします。CI が成功するはずです。

GitHub シークレット

CI ワークフローはリポジトリシークレットを3つ参照します。Settings → Secrets and variables → Actions から、または gh secret set を使って設定してください。

シークレット使用先生成方法
RELEASE_TOKENrelease-prepare.yml、release.yml、release-notes.yml、copier-update.yml、renovate.yml、bootstrap.ymlhttps://github.com/settings/personal-access-tokens/new で、contents: write、pull_requests: write、administration: write を付与した細粒度 PAT を作成します（bootstrap はリポジトリのルールセットと自動マージを適用します）。リポジトリ管理者のアカウントに属している必要があります。同梱のルールセットは管理者ロールにバイパス権限を付与しており、リリースのプルリクエストがマージされた後に knope が作成するリリースタグと GitHub リリースにも、この権限が必要です（トークンが作成するプルリクエストでも CI を実行するために必要です）。このリポジトリにスコープを限定してください。
CODECOV_TOKENci.ymlhttps://codecov.io：GitHub でサインインし、リポジトリを追加します。アップロードトークンは設定ページにあります。
CLAUDE_CODE_OAUTH_TOKENclaude.yml、claude-code-review.yml、release-notes.ymlローカルで claude setup-token を実行し、結果を貼り付けます。
gh secret set RELEASE_TOKEN
gh secret set CODECOV_TOKEN
gh secret set CLAUDE_CODE_OAUTH_TOKEN

依存関係の更新は Renovate（renovate.yml）が処理し、RELEASE_TOKEN を再利用します。uv.lock を維持し、CI Success チェックが成功すると、パッチ／マイナーアップデートを自動マージします。初回のプッシュ時には、bootstrap.yml が自動マージを有効にし、リポジトリのルールセット（.github/rulesets/）を適用します。ブランチごとの保護方針とバイパスモデルについては、リポジトリの保護を参照してください。GitHub Actions の更新は copier テンプレートで行われ、リポジトリごとではなく copier update を通じて反映されます。

GITHUB_TOKEN は自動的に提供されるため、操作は不要です。

ローカル開発

PR ゲート（CI と同じ内容）：

uv run pytest -x -q                                  # tests
uv run ruff check --fix . && uv run ruff format .    # lint + format
uv run mypy src/ tests/                              # type-check

pre-commit は各コミット時にゲートの一部を実行します。詳細は .pre-commit-config.yaml を、Hard PR Acceptance Gates の全内容は CLAUDE.md を参照してください。

トラブルシューティング

スキャフォールド済みプロジェクトの移動

uv sync は、venv の Python を指す絶対パスの shebang を持つ .venv/bin/* スクリプトを作成します。スキャフォールド後にリポジトリを移動すると（mv /old/path /new/path）、古い shebang が venv の site-packages とは異なるインタープリターを参照するため、uv run pytest は ModuleNotFoundError: No module named 'fastmcp' で失敗します。

修正方法：

rm -rf .venv
uv sync --all-extras --all-groups

uv run python -m pytest も、一時的な回避策として使用できます（古いエントリースクリプトの shim を経由しません）。

copier update 後の uv.lock の更新

copier update により新しい依存関係（pyproject.toml.jinja に追加された新しい extra など）が導入されると、CI のインストール手順で uv sync --locked が実行され、古いロックファイルを使った場合に失敗します。ローカルで uv lock を実行し、copier-update PR の承認とあわせて更新済みの uv.lock をコミットしてください。

CI では --locked（レビュー ワークフローでは --frozen）を指定してインストールするため、ジョブが自身のワークスペースで uv.lock を書き換えることはありません。再ロックするジョブは、修正したずれを隠してしまい、ワークスペースに変更があると同じジョブ内の後続の git checkout が失敗します。ロックファイルのずれは、無言の変更ではなく、明確なメッセージを伴うインストール手順の失敗として表示されます。

リンク

ドメイン設定

ドメイン環境変数には IMAGE_GENERATION_MCP_ プレフィックスを使用します。

変数デフォルト必須説明
IMAGE_GENERATION_MCP_A1111_HOST(none)NoIMAGE_GENERATION_MCP_SD_WEBUI_HOST の非推奨エイリアスです。使用すると警告がログに記録されます。
IMAGE_GENERATION_MCP_A1111_MODEL(none)NoIMAGE_GENERATION_MCP_SD_WEBUI_MODEL の非推奨エイリアスです。使用すると警告がログに記録されます。
IMAGE_GENERATION_MCP_READ_ONLYtrueNotrue の場合、書き込みタグ付きツール（画像生成、変換、アップロード）はクライアントに表示されません。これらを有効にするには false に設定します。
IMAGE_GENERATION_MCP_SCRATCH_DIR~/.image-generation-mcp/imagesNo生成画像の保存先ディレクトリです。初回使用時に自動作成されます。
IMAGE_GENERATION_MCP_OPENAI_API_KEY(none)NoOpenAI API キーです。設定すると OpenAI プロバイダー（gpt-image-2、gpt-image-1.5、dall-e-3）が有効になります。
IMAGE_GENERATION_MCP_GOOGLE_API_KEY(none)NoGoogle API キーです。設定すると Gemini プロバイダー（gemini-3.1-flash-image など）が有効になります。キーは https://aistudio.google.com/apikey で取得できます。
IMAGE_GENERATION_MCP_SD_WEBUI_HOST(none)NoSD WebUI のベース URL（例：http://localhost:7860）です。設定すると SD WebUI プロバイダーが有効になります。AUTOMATIC1111、Forge、reForge、Forge-neo と互換性があります。
IMAGE_GENERATION_MCP_SD_WEBUI_MODEL(none)NoSD WebUI のチェックポイント名です。モデルに対応したプリセット検出（SD 1.5／SDXL／Lightning）とチェックポイントの上書きに使用されます。未設定の場合は、インスタンスで現在使用中のモデルが使われます。
IMAGE_GENERATION_MCP_DEFAULT_PROVIDERautoNoキーワードによる自動選択が行われない場合に使用するプロバイダーです。auto、openai、gemini、sd_webui、placeholder を指定できます。auto は最初に設定されたプロバイダーを選択します。
IMAGE_GENERATION_MCP_TRANSFORM_CACHE_SIZE64Noメモリに保持する変換済み画像の結果（サイズ変更、切り抜き、形式変換）の最大数です。キャッシュを無効にするには 0 に設定します。
IMAGE_GENERATION_MCP_PAID_PROVIDERSopenaiNo費用が発生するプロバイダー名をカンマ区切りで指定します。これらを使用する前に、generate_image は確認（クライアントのエリシテーション）を求めます。値が空の場合はこのデフォルト値が使われます。確認を無効にするには、プロバイダー名を指定しない値（none など）を設定します。
IMAGE_GENERATION_MCP_STYLES_DIR~/.image-generation-mcp/stylesNoスタイルプリセットファイル（YAML フロントマター付き Markdown）のディレクトリです。存在しない場合は自動作成されます。
IMAGE_GENERATION_MCP_ALLOW_LOCAL_FILE_INPUTfalseNoローカルファイルシステムのパスから入力画像を読み込むことを許可します。デフォルトでは無効で、URL とアップロードのみが受け付けられます。
IMAGE_GENERATION_MCP_MAX_INPUT_IMAGE_BYTES20971520No受け付ける入力画像サイズの上限（バイト単位）です。
IMAGE_GENERATION_MCP_FETCH_TIMEOUT_S30.0Noリモート画像 URL（fetch_image および URL 入力）を取得する際の HTTP タイムアウト（秒）です。
IMAGE_GENERATION_MCP_TRANSFER_TTL_DEFAULT_S3600.0No呼び出し元が TTL を明示的に指定しない場合に使用する、リンクの有効期間（秒）です。
IMAGE_GENERATION_MCP_TRANSFER_TTL_MAX_S86400.0No呼び出し元が指定したリンク TTL に適用される上限（秒）です。
IMAGE_GENERATION_MCP_TRANSFER_GRACE_TTL_S60.0No成功後の猶予期間（秒）です。配信済みトークンの TTL はこの値まで短縮され、転送が停止した場合にこの期間内で再試行できます。
IMAGE_GENERATION_MCP_TRANSFER_LEASE_S60.0No実行中の予約について、クラッシュしたハンドラーを再取得できるようになるまでの期間（秒）です。
IMAGE_GENERATION_MCP_TRANSFER_MAX_UPLOAD_BYTES104857600No1 回のアップロードで許可される最大サイズ（バイト単位）です。
create_download_link／create_upload_link ツールと /transfer/{token} ルートは、BASE_URL が設定された HTTP または SSE トランスポートでのみ登録され、リンクトークンは IMAGE_GENERATION_MCP_KV_STORE_URL に保存されます。上記の IMAGE_GENERATION_MCP_TRANSFER_* 設定項目で、リンクの有効期間とアップロードの上限を調整できます。セキュリティ：IMAGE_GENERATION_MCP_ALLOW_LOCAL_FILE_INPUT を有効にすると、参照画像のパスを介して呼び出し元にサーバーのファイルシステムの読み取りアクセスが許可されます。信頼できる呼び出し元、またはローカルの単一ユーザー環境でのみ有効にしてください。

ドメイン設定フィールドは、src/image_generation_mcp/config.py 内の CONFIG-FIELDS-START／CONFIG-FIELDS-END センチネルの間に記述します。環境変数の読み取りには fastmcp_pvl_core.env(_ENV_PREFIX, "SUFFIX", default) を使用し、名前の一貫性を保ちます。フィールドの不変条件は、CONFIG-VALIDATE-START／CONFIG-VALIDATE-END センチネルの間にある __post_init__ に記述します。各フィールドの metadata の help と tags が上記の表を直接生成するため、正確かつ完全に記述してください。

主な設計上の判断

  • 機能フラグではなく、機能検出を備えたマルチプロバイダー構成。 各プロバイダーの discover_capabilities() は、起動時に実際にサポートしているアスペクト比／品質／形式／ネガティブプロンプトのサポート状況を報告します。ルーティングロジックはハードコードされた列挙型ではなく、機能情報を参照します。プロトコルを満たせば新しいプロバイダーを追加でき、ルーターの編集は不要です。（docs/decisions/0001-…、0002-…、0007-… を参照。）
  • プロバイダーごとの style_profile メタデータを list_providers で公開。 選択肢が限定されたプロバイダー（OpenAI、Gemini、placeholder）では完全一致キー検索を使用します。SD WebUI では、正規表現による優先順位付きパターンテーブルを使用します。プロファイルにはライフサイクルフラグ（current／legacy／deprecated）が含まれ、自動生成されるトップレベルの warnings 配列に反映されます。（docs/decisions/0009-… を参照。）
  • ハイブリッドなバックグラウンドタスク。 短い呼び出し（OpenAI は約 5 秒）では進捗をインラインでストリーミングします。長い呼び出し（SD WebUI は 30～180 秒）ではバックグラウンドタスクとして実行し、check_generation_status でポーリングします。クライアントは task=True でモードを選択できます。（docs/decisions/0005-… を参照。）
  • 画像アセットモデル：コンテンツアドレス方式のレジストリ＋サイドカー JSON メタデータ＋オンデマンド変換。 生成画像はフル解像度のオリジナルを保持します。image://{id}/view?format=webp&width=512&crop_x=… リソースでは、再生成せずに形式変換／サイズ変更／切り抜きをオンデマンドで実行できます。変換結果はキャッシュされます。（docs/decisions/0006-… を参照。）
  • スタイルライブラリ。 ユーザーが保存した Markdown のブリーフ（タグ／アスペクト比／品質を記述する YAML フロントマター付き）を、LLM がプロバイダーごとに解釈します。文面をそのままコピーして使用するものではありません。プロバイダーごとの style_profile とは異なり、スタイルライブラリはブリーフを表し、style_profile はモデルを表します。（区別については docs/decisions/0008-… と 0009-… を参照。）
  • fastmcp_pvl_core.ServerConfig を継承せずに合成。 ドメイン設定は CONFIG-FIELDS-START／CONFIG-FIELDS-END センチネルの間に記述します。環境変数の読み取りには fastmcp_pvl_core.env(...) を使用し、プレフィックスの命名に一貫性を持たせます。

コメント

Markdown 対応

MCP は初めてですか？

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。