imagine-mcp

2026-09-13 アーカイブ — このリポジトリはメンテナンスを終了しました。この MCP サーバーの代わりに、画像プロバイダーのネイティブ API を使用してください。既存のインストールは引き続き動作しますが、更新やサポートは提供されません。

imagine-mcp

mcp-name: io.github.n24q02m/imagine-mcp

Gemini、OpenAI、Grok に対応した、AI エージェント向けの画像・動画理解と生成。

n24q02m の姉妹プロジェクト（クリックして展開）

| プロジェクト | キャッチコピー | タグ | |---|---|---| | [agent-chat-plugin](https://github.com/n24q02m/agent-chat-plugin) | AI エージェント同士が共有フォルダーでチャット — 人間の中継もオーケストレーターも不要、wor... | Tooling | | [better-code-review-graph](https://github.com/n24q02m/better-code-review-graph) | トークン効率に優れたコードレビューのためのナレッジグラフ — セマンティック検索と呼び出し... | MCP | | [better-drive](https://github.com/n24q02m/better-drive) | .driveignore フィルター対応の双方向 Google Drive 同期 — rclone エンジン、Windows トレイ | Tooling | | [better-email-mcp](https://github.com/n24q02m/better-email-mcp) | AI エージェント向け IMAP/SMTP メール — 読み取り、送信、フォルダー整理、属性の管理... | MCP | | [better-godot-mcp](https://github.com/n24q02m/better-godot-mcp) | Godot Engine 向けの複合 MCP サーバー — AI を活用したゲーム開発のための17個の複合ツール... | MCP | | [better-notion-mcp](https://github.com/n24q02m/better-notion-mcp) | AI エージェント向けの Markdown ファーストな Notion — ページ、データベース、ブロック、コメント... | MCP | | [better-semantic-release](https://github.com/n24q02m/better-semantic-release) | リリース安全性ガードを内蔵した、すぐに使える python-semantic-release のフォーク（orp... | Tooling | | [better-telegram-mcp](https://github.com/n24q02m/better-telegram-mcp) | AI エージェント向け Telegram — 両方のボ...でメッセージ、チャット、メディア、連絡先を管理 | MCP | | [better-workspace-mcp](https://github.com/n24q02m/better-workspace-mcp) | Google Workspace MCP サーバー（Docs/Drive/Calendar/Gmail/Sheets/Slides/Tasks/Ch...） | MCP | | [claude-plugins](https://github.com/n24q02m/claude-plugins) | n24q02m MCP サーバー向け Claude Code プラグインマーケットプレイス — Web 検索をインストール... | Marketplace | | [imagine-mcp](https://github.com/n24q02m/imagine-mcp) | AI エージェント向けの画像・動画の理解と生成 — Gemini、Op...などに対応 | MCP | | [jules-task-archiver](https://github.com/n24q02m/jules-task-archiver) | batchexecute API を介した Jules タスクの一括操作用 Chrome Extension — a... | Tooling | | [mcp-core](https://github.com/n24q02m/mcp-core) | MCP サーバー構築のための共通基盤 — Streamable HTTP トランスポート、OAuth... | MCP | | [mnemo-mcp](https://github.com/n24q02m/mnemo-mcp) | ハイブリッド検索と埋め込み同期に対応した永続的な AI メモリー。オープン、無料、無制限... | MCP | | [qwen3-embed](https://github.com/n24q02m/qwen3-embed) | ONNX Runtime と GGUF による軽量な Qwen3 テキスト埋め込みとリランキング | Library | | [skret](https://github.com/n24q02m/skret) | サーバー不要のシークレット管理。 | CLI | | [tacet](https://github.com/n24q02m/tacet) | ナレッジ全体にわたって LLM のコストを償却する、自己蒸留型のニューロシンボリック・カスケード... | Tooling | | [web-core](https://github.com/n24q02m/web-core) | 検索、スクレイピング、HTTP セキュリティ、st...向けの共通 Web インフラストラクチャパッケージ | Library | | [wet-mcp](https://github.com/n24q02m/wet-mcp) | AI エージェント向けのオープンソース MCP サーバー：Web 検索、コンテンツ抽出、ライブラリ... | MCP |

目次

• 機能
• インストール
• Smithery
• 設定
• CLI
• リモート（HTTP モード）
• ドキュメント
• ツール
• 比較
• セキュリティ
• ソースからビルド
• Cloudflare へのデプロイ
• デプロイ
• 信頼モデル
• コントリビューション
• ライセンス

## 機能

• マルチモーダル理解 -- 画像や動画の説明、分類、推論を行います（Gemini は 1 回の呼び出しで画像と動画の混在に対応します）
• 画像生成 -- Gemini Imagen、OpenAI gpt-image、Grok Imagine によるテキストからの画像生成と、画像からの画像生成（編集／インペイント）に対応します
• 動画生成 -- テキストからの動画生成と、画像からの動画生成（Gemini Veo 3.1、Grok Imagine Video）に対応します
• 3 プロバイダー x 2 ティア -- poor（低コスト／高速）または rich（高品質）で、gemini／openai／grok に共通のインターフェースを提供します。パラメーターで切り替えられます
• オープンモデルのパススルー -- 理解処理は litellm 経由でルーティングされます。任意の provider/model を渡すか、順序付きのモデルチェーンを設定できます（モデルカタログのハードコードはありません）
• 縮退モード -- 認証情報がなくてもサーバーが起動し、キーを追加すると利用可能なプロバイダーが表示されます
• レスポンスキャッシュ -- understand のレスポンスをディスクにキャッシュします。TTL は設定可能です
• デュアルトランスポート -- プロバイダーの環境変数を使う純粋な stdio（デフォルト）、またはトークンを貼り付けるリレーフォームを備えた HTTP マルチユーザー方式

インストール

インストール不要の uvx で実行するか、コンテナイメージを取得します：

# uvx -- recommended, runs the published PyPI package
uvx imagine-mcp

# Docker
docker run -it --rm ghcr.io/n24q02m/imagine-mcp:latest

クライアントの接続先を uvx imagine-mcp コマンドに設定し、少なくとも 1 つのプロバイダーキーを指定して、MCP クライアントに追加します（設定を参照）：

{
  "mcpServers": {
    "imagine": {
      "command": "uvx",
      "args": ["imagine-mcp"],
      "env": { "GEMINI_API_KEY": "AIza..." }
    }
  }
}

クライアントごとの設定例（Claude Code、Codex、Gemini CLI、Cursor、Windsurf）とブラウザベースの HTTP セットアップについては、セットアップドキュメントを参照してください。

AI エージェントでインストール -- 次の内容を AI コーディングエージェントに貼り付けます：

手順に従って MCP サーバー imagine-mcp をインストールしてください： https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/imagine-mcp/setup-with-agent.md

Smithery

imagine-mcp には smithery.yaml が同梱されているため、Smithery 経由でインストールして実行できます。このエントリーは、空の設定スキーマで公開済みの PyPI パッケージを stdio 経由で起動します（uvx --python 3.13 imagine-mcp）。デプロイ時に設定項目は必要ありません。プロバイダーキーは、実行時にサーバー独自の認証情報フローで指定します（stdio モードでは環境変数、HTTP モードではブラウザーのセットアップフォームを使用します。設定を参照）。

設定

2 種類のトランスポートがあります（デフォルトは stdio。--http、MCP_TRANSPORT=http、または TRANSPORT_MODE=http で http を選択できます）：

• stdio（デフォルト）-- シングルユーザー方式で、環境変数からのみ認証情報を読み込みます。3 つのプロバイダーキーがいずれも設定されていない場合は終了します。
• http -- HTTP デーモンです。デフォルトでは 127.0.0.1 上でローカルにセルフホストできます。また、PUBLIC_URL と MCP_DCR_SERVER_SECRET が設定されている場合は、リモートのマルチユーザー方式（JWT のサブジェクトごとに認証情報を分離）で動作します。HTTP モードでは、/authorize のブラウザーフォームから認証情報を入力します。

プロバイダーキー

すべて任意です。サーバーは縮退モードで起動し、キーが設定されているプロバイダーを利用可能にします。少なくとも 1 つ設定してください。

環境変数	プロバイダー	キーの取得先
GEMINI_API_KEY	Gemini（画像 + 動画）	aistudio.google.com/apikey
OPENAI_API_KEY	OpenAI（画像）	platform.openai.com/api-keys
XAI_API_KEY	Grok / xAI（画像 + 動画）	console.x.ai

ツールの呼び出し時に provider が明示されていない場合は、XAI_API_KEY -> OPENAI_API_KEY -> GEMINI_API_KEY の順に、最初に見つかったキーが使用されます。

モデルチェーン（任意）

モデルの選択は、understandではlitellmに、generateではネイティブの プロバイダーSDKにそのまま渡されます。ハードコードされたモデルカタログはありません。各チェーンはlitellmの provider/modelエントリーをCSV形式で並べたもので、記載順にフォールバックします。

環境変数	用途
UNDERSTAND_MODELS	understand用のモデルチェーン（litellmのフォールバック）。空で、明示的なmodelも指定されていない場合、understandはエラーになります（組み込みのデフォルト値はありません）。
GENERATE_MODELS	generate用のモデルチェーン。最初のエントリーでネイティブプロバイダーとモデルが選択されます。空の場合は、プロバイダー独自の最小限の組み込みデフォルト値が使われます。
GENERATE_PROVIDER_PRIORITY	生成時の自動フォールバックでプロバイダーの順序を変更するCSV形式のプロバイダー名一覧。デフォルトはgrok,openai,geminiです。

理解処理はlitellm経由でルーティングされるため（provider/modelをそのまま渡します）、 litellmのあらゆるプロバイダーを利用できます。該当するプロバイダーの<PROVIDER>_API_KEYを指定してください。 生成処理では、引き続きネイティブのプロバイダーSDK（Gemini、OpenAI、Grok）を使用します。例：

{
  "mcpServers": {
    "imagine": {
      "command": "uvx",
      "args": ["imagine-mcp"],
      "env": {
        "UNDERSTAND_MODELS": "gemini/<model-id>,openai/<model-id>",
        "GEMINI_API_KEY": "AIza...",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

実行時の設定項目

config(action="set", key=..., value=...)を使うと、実行時にlog_level、default_provider、 default_tier、cache_ttl_secondsを調整できます。

CLI

パッケージによってインストールされるimagine-mcpコンソールコマンドにはサブコマンドがありません。 実行すると、MCP サーバーが直接起動します。トランスポートは、1つのフラグまたは対応する環境変数で選択します。

imagine-mcp            # stdio transport (default); reads provider keys from env vars
imagine-mcp --http     # HTTP daemon; credentials via the browser setup form

起動方法	対応する環境変数	結果
imagine-mcp	MCP_TRANSPORT未設定	stdio、シングルユーザー、環境変数の認証情報
imagine-mcp --http	MCP_TRANSPORT=http（またはTRANSPORT_MODE=http）	HTTPデーモン。ローカルの127.0.0.1でセルフホストするか、PUBLIC_URLとMCP_DCR_SERVER_SECRETを設定して複数ユーザー向けのリモートサーバーとして実行します。

stdioモードでは、プロバイダーキーが1つも設定されていない場合、サーバーは終了します。リモートHTTPのバインド設定（MCP_HOST、MCP_PORT）は、PUBLIC_URLが設定されている場合にのみ適用されます。Configurationを参照してください。

リモート（HTTPモード）

HTTPデプロイでは、リモートHTTP MCP サーバーに対応したクライアントにサービスを提供します。OAuthによる認証が必須です。認証されていないリクエストには、WWW-Authenticate: Bearerチャレンジとともに401が返されます。認証情報はブラウザーのセットアップフォームから設定します。HTTPに対応したMCPクライアントで https://<your-host>/mcpに接続し、OAuthフローを完了してください。 デプロイ方法については、Deploy to Cloudflareを参照してください。

ドキュメント

詳細なドキュメントは**mcp.n24q02m.com/servers/imagine-mcp/setup/**にあります。

• セットアップ — Claude Code、Codex、Gemini CLI、Cursor、Windsurf、mcp.json向けのインストール方法
• モードの概要 — stdio／ローカルリレー／リモートリレー／リモートOAuth
• 複数ユーザー向けセットアップ — JWTのsubごとに認証情報を管理するモデル

ツール

4 つの MCP ツール（understand、generate、config、help）と、config__open_relay（mcp-core によってフレームワークから注入されます）があります。

ツール	アクション	説明
understand	--	1 つ以上の画像／動画 URL について説明または推論します。media_urls: list[str]、prompt: str、provider、tier、max_tokens を指定します。
generate	--	テキストプロンプトから画像または動画を生成します。media_type: image|video、任意の reference_image_url、任意の job_id（動画のポーリング用）、aspect_ratio、duration_seconds を指定します。
config	setup_status、setup_skip、setup_reset、setup_complete、warmup、status、set、cache_clear（relay_status／relay_skip／relay_reset／relay_complete は非推奨のエイリアスとして引き続き利用できます）	認証情報とランタイム設定を管理します。認証情報の状態を確認し、ランタイム設定（ログレベル、デフォルトのプロバイダー、TTL）を設定し、レスポンスキャッシュをクリアします。
help	--	understand、generate、config のトピックに関する Markdown 形式のドキュメント全体を表示します。
config__open_relay	--	フレームワークから注入されるヘルパー（mcp-core）で、ブラウザーの認証情報フォームを開きます。

モデルの選択は呼び出し元が行います（litellm の provider/model をそのまま渡すか、*_MODELS 環境変数チェーンを使用します）。詳しくは上記のモデルチェーンを参照してください。

比較

各機能の柱について、imagine-mcp と直接の競合製品を比較します。

機能	imagine-mcp	EverArt MCP	fal.ai MCP	Replicate Flux MCP
画像／動画の理解	はい（画像と動画の URL の説明／分類／推論）	いいえ	いいえ	いいえ
画像生成	はい（テキストから画像、および reference_image_url を使った画像から画像への生成）	はい（単一の generate_image）	はい（テキスト／画像から画像への生成、編集、インペインティング）	はい（単一の generate_image）
動画生成	はい（テキストから動画、および画像から動画への生成、非同期の job_id ポーリング）	いいえ	はい（テキスト／画像から動画への生成）	いいえ
マルチプロバイダーのバックエンド	はい（Gemini／OpenAI／Grok、自動フォールバック）	いいえ（EverArt のみ）	いいえ（fal.ai のみ）	いいえ（Replicate Flux のみ）
品質／コストのティア	はい（poor は低コスト・高速、rich はプロバイダーごとの高品質設定）	いいえ	いいえ	いいえ
セルフホスト可能／オープンソース	はい（Apache-2.0、stdio と HTTP によるセルフホスト）	はい（MIT、アーカイブ済み）	はい（MIT）	はい（MIT、アーカイブ済み）

セキュリティ

• SSRF と LFI の防止 -- すべての media_urls と reference_image_url はディスパッチ境界で検証され、プロバイダーに渡されるのは http:// と https:// スキームのみです。file://、ftp://、gopher://、およびスキームのない URL は拒否されます。
• エラーに認証情報を含めない -- プロバイダー側のエラーは、返却前にサニタイズされます。
• 機能を縮退させた起動 -- 認証情報がなくてもサーバーの起動は妨げられません。影響を受けるアクションは起動時にクラッシュするのではなく、対処方法がわかるエラーを表示します。
• 認証情報の保存 -- ブラウザーの認証情報フォームから送信された認証情報は、mcp-core によって暗号化され（AES-GCM、マシンに紐付けられたキー）、~/.imagine-mcp/config.json に保存されます。

ワークスペースのユーザー名（HTTP セットアップフォーム）

ブラウザーの認証情報フォームには、任意のワークスペースのユーザー名フィールドがあります。同じユーザー名を入力すると、常に同じ sub ごとのバケットに割り当てられるため、各 /authorize の往復処理で発行される一時的なサブジェクトに紐付けられることなく、再認証後もデバイス間でもプロバイダーのキーを引き続き利用できます。空欄のままにすると、従来の認可ごとの動作が維持されます。

信頼境界：フォームが共有の MCP_RELAY_PASSWORD で保護されている場合、ユーザー名はシークレットではなくパーティションキーです。そのパスワードを知っている人なら誰でも任意のユーザー名を入力して、そのバケットにアクセスできます。信頼できるグループであれば問題ありませんが、信頼できない複数テナントのデプロイでは、ユーザーごとのシークレットまたは委任 OAuth が必要です。

**一度限りの移行：**既存のユーザーは、この変更後に一度だけ認証情報を再入力する必要があります。削除される情報はありません。以前のランダムなサブジェクトの下に保存された認証情報が、単に参照されなくなります。

ソースからビルドする

git clone https://github.com/n24q02m/imagine-mcp.git
cd imagine-mcp
mise run setup      # or: uv sync --group dev
mise run dev        # run the server in stdio mode (add --http for the HTTP daemon)

Cloudflare にデプロイする

Cloudflare 上で、Imagine インスタンスをサーバーレスで実行できます（Worker + Container + KV）。ストレージ は KV のみです。ユーザーごとの認証情報ボルトは KV に保存され、コンテナのファイルシステムは一時的なため、 生成結果は base64 のみで返されます（IMAGINE_OUTPUT_MODE=base64）。

前提条件： Containers に必要な Cloudflare の Workers Paid プランのアカウント（Cloudflare の無料プランには Containers が含まれません）と、wrangler CLI が必要です。

1. git clone https://github.com/n24q02m/imagine-mcp && cd imagine-mcp
2. wrangler login
3. KV namespace を作成します（Imagine は KV のみを使用し、D1 や Vectorize は使用しません）。その後、返された id を wrangler.jsonc の <imagine-kv-namespace-id> プレースホルダーに貼り付けます。

   wrangler kv namespace create imagine-kv
   

4. コンテナイメージを Cloudflare のマネージドレジストリにプッシュします（CF Containers は外部レジストリから直接プルできません）。その後、wrangler.jsonc の <YOUR_ACCOUNT_ID> を設定します。

   docker pull ghcr.io/n24q02m/imagine-mcp:beta
   docker tag ghcr.io/n24q02m/imagine-mcp:beta imagine-mcp:beta
   wrangler containers push imagine-mcp:beta   # prints registry.cloudflare.com/<ACCOUNT_ID>/imagine-mcp:beta
   

5. wrangler.jsonc の残りのプレースホルダーを独自のドメインに設定します。<YOUR_PUBLIC_URL> （vars.PUBLIC_URL。例：https://imagine.example.com）と <YOUR_WORKER_DOMAIN> （routes のカスタムドメインパターン。例：imagine.example.com）です。
6. シークレットを設定します。CREDENTIAL_SECRET（安定した JWT 署名キー + ユーザーごとのボルトキー）と MCP_DCR_SERVER_SECRET（意図的なマルチユーザーデプロイであることの証明）が必須です。 MCP_RELAY_PASSWORD はブラウザーのセットアップフォームへのログインを制限します。プロバイダーキーは サーバーのデフォルトとして任意で設定できますが、通常、ユーザーは代わりにセットアップフォームから自身のキーを貼り付けます。

   wrangler secret put CREDENTIAL_SECRET
   wrangler secret put MCP_DCR_SERVER_SECRET
   wrangler secret put MCP_RELAY_PASSWORD
   wrangler secret put GEMINI_API_KEY       # optional provider default
   wrangler secret put OPENAI_API_KEY       # optional provider default
   wrangler secret put XAI_API_KEY          # optional provider default
   

7. wrangler deploy を実行し、Worker ドメインを開いて、ブラウザーのリレーフォームでセットアップを完了します。

http コンテナイメージは、すでにマルチユーザーモードで実行されます（MCP_TRANSPORT=http はイメージのターゲットに組み込まれています）。ストレージは MCP_STORAGE_BACKEND=cf-kv（暗号化された認証情報ボルト）で Cloudflare に対応付けられます。また、IMAGINE_OUTPUT_MODE=base64 により、base64 のレスポンスが強制されるため、一時的なコンテナファイルシステムにメディアパスが書き込まれることはありません。

デプロイ

Cloudflare へのデプロイは CD で管理されています。リリースを公開すると、 .github/workflows/cd.yml の deploy-cf ジョブが実行され、 リリースされたタグをチェックアウトし、リリースバージョンのタグを付けた http-slim コンテナイメージを ビルドして Cloudflare のマネージドレジストリにプッシュし、Worker + Container スタックをデプロイした後、 カナリアで確認します。カナリアに失敗した場合は、不適切なデプロイが反映されるのではなく、ジョブが失敗します。そのため、稼働中のイメージは常にリリース済みの不変なイメージタグに対応します。このデプロイに対して手動で wrangler deploy を実行すると、リリースとタグの対応関係が崩れるため、サポート対象の方法ではありません。代わりに独自のインスタンスを実行するには、 Cloudflare にデプロイするを参照してください。

現在、このジョブは無効になっています。リポジトリの Actions 変数 CF_HOSTED_ENABLED が false に設定されているため、リリース時に自動デプロイされず、 ホストされたエンドポイントも運用されていません。現在利用可能な HTTP の方法は、上記のセルフホストです。

信頼モデル

このプラグインは TC-Local（マシンにバインドされた単一の信頼主体）を実装しています。分類の詳細については、mcp-core の信頼モデルを参照してください。

モード	ストレージ	暗号化	データを読み取れるユーザー
stdio（デフォルト）	~/.imagine-mcp/config.json	AES-GCM、マシンにバインドされたキー	OS ユーザーのみ（ファイル権限 0600）
HTTP セルフホスト	stdio と同じ	同じ	あなたのみ（管理者 = ユーザー）

コントリビューション

開発ワークフロー、コミット規約、リリースプロセスの詳細については、CONTRIBUTING.md を参照してください。Issue と Discussions も歓迎します。

ライセンス

Apache-2.0 — 詳細については LICENSE を参照してください。