{ "markdown": "# imagine-mcp\n\nmcp-name: io.github.n24q02m/imagine-mcp\n\n**Image and video understanding + generation for AI agents -- across Gemini, OpenAI, and Grok.**\n\n\n[![CI](https://github.com/n24q02m/imagine-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/n24q02m/imagine-mcp/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/n24q02m/imagine-mcp/graph/badge.svg)](https://codecov.io/gh/n24q02m/imagine-mcp)\n[![PyPI](https://img.shields.io/pypi/v/imagine-mcp?logo=pypi&logoColor=white)](https://pypi.org/project/imagine-mcp/)\n[![Docker](https://img.shields.io/docker/v/n24q02m/imagine-mcp?label=docker&logo=docker&logoColor=white&sort=semver)](https://hub.docker.com/r/n24q02m/imagine-mcp)\n[![License: Apache-2.0](https://img.shields.io/github/license/n24q02m/imagine-mcp)](LICENSE)\n\n\n[![Python](https://img.shields.io/badge/Python-3776AB?logo=python&logoColor=white)](#)\n[![FastMCP](https://img.shields.io/badge/FastMCP-purple?logo=anthropic&logoColor=white)](#)\n[![MCP](https://img.shields.io/badge/MCP-000000?logo=anthropic&logoColor=white)](#)\n[![semantic-release](https://img.shields.io/badge/semantic--release-e10079?logo=semantic-release&logoColor=white)](https://github.com/python-semantic-release/python-semantic-release)\n[![Renovate](https://img.shields.io/badge/renovate-enabled-1A1F6C?logo=renovatebot&logoColor=white)](https://developer.mend.io/)\n\n\n
\n Sister projects from n24q02m (click to expand)\n\n| Project | Tagline | Tag |\n|---|---|---|\n| [agent-chat-plugin](https://github.com/n24q02m/agent-chat-plugin) | Peer AI agents chat in a shared folder — no human relay, no orchestrator, wor... | Tooling |\n| [better-code-review-graph](https://github.com/n24q02m/better-code-review-graph) | Knowledge graph for token-efficient code reviews -- semantic search and call-... | MCP |\n| [better-drive](https://github.com/n24q02m/better-drive) | 2-way Google Drive sync with .driveignore filter — rclone engine, Windows tray | Tooling |\n| [better-email-mcp](https://github.com/n24q02m/better-email-mcp) | IMAP/SMTP email for AI agents -- read, send, organize folders, and manage att... | MCP |\n| [better-godot-mcp](https://github.com/n24q02m/better-godot-mcp) | Composite MCP server for Godot Engine -- 17 composite tools for AI-assisted g... | MCP |\n| [better-notion-mcp](https://github.com/n24q02m/better-notion-mcp) | Markdown-first Notion for AI agents -- pages, databases, blocks, and comments... | MCP |\n| [better-semantic-release](https://github.com/n24q02m/better-semantic-release) | Drop-in python-semantic-release fork with built-in release-safety guards (orp... | Tooling |\n| [better-telegram-mcp](https://github.com/n24q02m/better-telegram-mcp) | Telegram for AI agents -- messages, chats, media, and contacts across both bo... | MCP |\n| [better-workspace-mcp](https://github.com/n24q02m/better-workspace-mcp) | Google Workspace MCP server (Docs/Drive/Calendar/Gmail/Sheets/Slides/Tasks/Ch... | MCP |\n| [claude-plugins](https://github.com/n24q02m/claude-plugins) | Claude Code plugin marketplace for the n24q02m MCP servers -- install web sea... | Marketplace |\n| [imagine-mcp](https://github.com/n24q02m/imagine-mcp) | Image and video understanding + generation for AI agents -- across Gemini, Op... | MCP |\n| [jules-task-archiver](https://github.com/n24q02m/jules-task-archiver) | Chrome Extension for bulk operations on Jules tasks via batchexecute API -- a... | Tooling |\n| [mcp-core](https://github.com/n24q02m/mcp-core) | Shared foundation for building MCP servers -- Streamable HTTP transport, OAut... | MCP |\n| [mnemo-mcp](https://github.com/n24q02m/mnemo-mcp) | Persistent AI memory with hybrid search and embedded sync. Open, free, unlimi... | MCP |\n| [qwen3-embed](https://github.com/n24q02m/qwen3-embed) | Lightweight Qwen3 text embedding and reranking via ONNX Runtime and GGUF | Library |\n| [skret](https://github.com/n24q02m/skret) | Secrets without the server. | CLI |\n| [tacet](https://github.com/n24q02m/tacet) | A self-distilling neuro-symbolic cascade that amortises LLM cost across knowl... | Tooling |\n| [web-core](https://github.com/n24q02m/web-core) | Shared web infrastructure package for search, scraping, HTTP security, and st... | Library |\n| [wet-mcp](https://github.com/n24q02m/wet-mcp) | Open-source MCP server for AI agents: web search, content extraction, and lib... | MCP |\n\n
\n\n\n## Table of contents\n\n- [Features](#features)\n- [Install](#install)\n- [Smithery](#smithery)\n- [Configuration](#configuration)\n- [CLI](#cli)\n- [Remote (HTTP mode)](#remote-http-mode)\n- [Documentation](#documentation)\n- [Tools](#tools)\n- [Comparison](#comparison)\n- [Security](#security)\n- [Build from Source](#build-from-source)\n- [Deploy to Cloudflare](#deploy-to-cloudflare)\n- [Trust Model](#trust-model)\n- [Contributing](#contributing)\n- [License](#license)\n\n\n\n\n \"imagine-mcp\n\n\n## Features\n\n- **Multimodal understanding** -- Describe, classify, or reason over images and videos (Gemini handles mixed image + video in one call)\n- **Image generation** -- Text-to-image and image-to-image (edit / inpaint) across Gemini Imagen, OpenAI gpt-image, Grok Imagine\n- **Video generation** -- Text-to-video and image-to-video (Gemini Veo 3.1, Grok Imagine Video)\n- **3 providers x 2 tiers** -- Same interface for `gemini` / `openai` / `grok` at `poor` (cheap/fast) or `rich` (high quality); swap via parameter\n- **Open model passthrough** -- Understanding routes through litellm; pass any `provider/model`, or configure an ordered model chain (no hardcoded catalog)\n- **Degraded mode** -- Server starts with zero credentials and surfaces remaining providers as you add keys\n- **Response cache** -- Disk-based caching of `understand` responses with configurable TTL\n- **Dual transport** -- pure stdio with provider env vars (default) or HTTP multi-user with paste-token relay form\n\n## Install\n\nRun with [`uvx`](https://docs.astral.sh/uv/) (no install step) or pull the container image:\n\n```bash\n# uvx -- recommended, runs the published PyPI package\nuvx imagine-mcp\n\n# Docker\ndocker run -it --rm ghcr.io/n24q02m/imagine-mcp:latest\n```\n\nAdd it to an MCP client by pointing the client at the `uvx imagine-mcp` command and\nsupplying at least one provider key (see [Configuration](#configuration)):\n\n```json\n{\n \"mcpServers\": {\n \"imagine\": {\n \"command\": \"uvx\",\n \"args\": [\"imagine-mcp\"],\n \"env\": { \"GEMINI_API_KEY\": \"AIza...\" }\n }\n }\n}\n```\n\nFor per-client snippets (Claude Code, Codex, Gemini CLI, Cursor, Windsurf) and the\nbrowser-based HTTP setup, see the [Setup docs](https://mcp.n24q02m.com/servers/imagine-mcp/setup/).\n\n**Install with an AI agent** -- paste this to your AI coding agent:\n\n> Install MCP server `imagine-mcp` following the steps at\n> https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/imagine-mcp/setup-with-agent.md\n\n## Smithery\n\nimagine-mcp ships a [`smithery.yaml`](smithery.yaml) so it can be installed and\nrun through [Smithery](https://smithery.ai). The entry launches the published\nPyPI package over stdio (`uvx --python 3.13 imagine-mcp`) with an empty config\nschema -- no setup fields are required at deploy time. Provider keys are supplied\nat runtime through the server's own credential flow (env vars in stdio mode, or\nthe browser setup form in HTTP mode; see [Configuration](#configuration)).\n\n## Configuration\n\nTwo transports (default `stdio`; opt into `http` with `--http`, `MCP_TRANSPORT=http`,\nor `TRANSPORT_MODE=http`):\n\n- **stdio** (default) -- single-user, reads credentials from env vars only. Exits if\n none of the three provider keys are set.\n- **http** -- HTTP daemon. Local self-host on `127.0.0.1` by default, or multi-user\n remote (per-JWT-sub credential isolation) when `PUBLIC_URL` + `MCP_DCR_SERVER_SECRET`\n are set. In HTTP mode credentials are entered through a browser form at `/authorize`.\n\n### Provider keys\n\nAll optional -- the server starts in degraded mode and surfaces whichever providers\nhave a key. Set at least one.\n\n| Env var | Provider | Get a key at |\n|---|---|---|\n| `GEMINI_API_KEY` | Gemini (image + video) | aistudio.google.com/apikey |\n| `OPENAI_API_KEY` | OpenAI (image) | platform.openai.com/api-keys |\n| `XAI_API_KEY` | Grok / xAI (image + video) | console.x.ai |\n\nWhen a tool is called without an explicit `provider`, the first key present wins in the\norder `XAI_API_KEY` -> `OPENAI_API_KEY` -> `GEMINI_API_KEY`.\n\n### Model chains (optional)\n\nModel choice passes straight through to litellm (`understand`) or the native\nprovider SDK (`generate`) -- there is no hardcoded model catalog. Each chain is a\nCSV of litellm `provider/model` entries; the order is the fallback order.\n\n| Env var | Purpose |\n|---|---|\n| `UNDERSTAND_MODELS` | Ordered model chain for `understand` (litellm fallback). Empty and no explicit `model` -> `understand` fails loud (no built-in default). |\n| `GENERATE_MODELS` | Ordered model chain for `generate`. The first entry selects the native provider + model. Empty -> the provider's own minimal built-in default. |\n| `GENERATE_PROVIDER_PRIORITY` | CSV of provider names reordering generation auto-fallback. Defaults to `grok,openai,gemini`. |\n\nUnderstanding is routed through litellm (`provider/model` passthrough), so any litellm\nprovider works -- supply that provider's `_API_KEY`. Generation stays on the\nnative provider SDKs (Gemini, OpenAI, Grok). Example:\n\n```json\n{\n \"mcpServers\": {\n \"imagine\": {\n \"command\": \"uvx\",\n \"args\": [\"imagine-mcp\"],\n \"env\": {\n \"UNDERSTAND_MODELS\": \"gemini/,openai/\",\n \"GEMINI_API_KEY\": \"AIza...\",\n \"OPENAI_API_KEY\": \"sk-...\"\n }\n }\n }\n}\n```\n\n### Runtime knobs\n\n`config(action=\"set\", key=..., value=...)` adjusts `log_level`, `default_provider`,\n`default_tier`, and `cache_ttl_seconds` at runtime.\n\n## CLI\n\nThe `imagine-mcp` console command installed by the package takes **no\nsubcommands** -- it starts the MCP server directly. Transport is selected by a\nsingle flag or its environment-variable equivalents:\n\n```bash\nimagine-mcp # stdio transport (default); reads provider keys from env vars\nimagine-mcp --http # HTTP daemon; credentials via the browser setup form\n```\n\n| Invocation | Equivalent env | Result |\n|---|---|---|\n| `imagine-mcp` | `MCP_TRANSPORT` unset | stdio, single-user, env-var credentials |\n| `imagine-mcp --http` | `MCP_TRANSPORT=http` (or `TRANSPORT_MODE=http`) | HTTP daemon -- local `127.0.0.1` self-host, or multi-user remote when `PUBLIC_URL` + `MCP_DCR_SERVER_SECRET` are set |\n\nIn stdio mode the server exits if none of the provider keys are set. The remote\nHTTP bind knobs (`MCP_HOST`, `MCP_PORT`) apply only when `PUBLIC_URL` is set; see\n[Configuration](#configuration).\n\n## Remote (HTTP mode)\n\nAn HTTP deployment serves clients that support remote HTTP MCP servers. It is\nOAuth-gated -- an unauthenticated request returns `401` with a\n`WWW-Authenticate: Bearer` challenge -- and credentials are provisioned through\nthe browser setup form. Point an HTTP-capable MCP client at\n`https:///mcp` and complete the OAuth flow to connect.\nTo stand one up, see [Deploy to Cloudflare](#deploy-to-cloudflare).\n\n## Documentation\n\nFull docs at **[mcp.n24q02m.com/servers/imagine-mcp/setup/](https://mcp.n24q02m.com/servers/imagine-mcp/setup/)**:\n\n- [Setup](https://mcp.n24q02m.com/servers/imagine-mcp/setup/) -- install methods for Claude Code, Codex, Gemini CLI, Cursor, Windsurf, mcp.json\n- [Modes overview](https://mcp.n24q02m.com/get-started/modes-overview/) -- stdio / local-relay / remote-relay / remote-oauth\n- [Multi-user setup](https://mcp.n24q02m.com/get-started/multi-user/) -- per-JWT-sub credential model\n\n## Tools\n\n| Tool | Actions | Description |\n|:-----|:--------|:------------|\n| `understand` | -- | Describe or reason over one or more image/video URLs. `media_urls: list[str]`, `prompt: str`, `provider`, `tier`, `max_tokens`. |\n| `generate` | -- | Generate an image or video from a text prompt. `media_type: image\\|video`, optional `reference_image_url`, optional `job_id` (video poll), `aspect_ratio`, `duration_seconds`. |\n| `config` | `setup_status`, `setup_skip`, `setup_reset`, `setup_complete`, `warmup`, `status`, `set`, `cache_clear` (`relay_status`/`relay_skip`/`relay_reset`/`relay_complete` honored as deprecated aliases) | Credential + runtime config: check credential state, set runtime knobs (log level, default provider, TTL), clear response cache. |\n| `help` | -- | Full Markdown documentation for `understand`, `generate`, or `config` topics. |\n| `config__open_relay` | -- | Framework-injected helper (mcp-core); opens the browser credential form. |\n\nModel choice is caller-driven (litellm `provider/model` passthrough or a `*_MODELS`\nenv chain) -- see [Model chains](#configuration) above.\n\n## Comparison\n\nHow imagine-mcp stacks up against direct competitors in each pillar:\n\n| Capability | imagine-mcp | EverArt MCP | fal.ai MCP | Replicate Flux MCP |\n|---|---|---|---|---|\n| Image/video understanding | Yes (describe / classify / reason over image + video URLs) | No | No | No |\n| Image generation | Yes (text-to-image + image-to-image via `reference_image_url`) | Yes (single `generate_image`) | Yes (text/image-to-image, edit, inpaint) | Yes (single `generate_image`) |\n| Video generation | Yes (text-to-video + image-to-video, async `job_id` poll) | No | Yes (text/image-to-video) | No |\n| Multi-provider backends | Yes (Gemini / OpenAI / Grok, auto-fallback) | No (EverArt only) | No (fal.ai only) | No (Replicate Flux only) |\n| Quality/cost tiers | Yes (`poor` cheap-fast vs `rich` high-quality per provider) | No | No | No |\n| Self-hostable / open source | Yes (Apache-2.0, stdio + HTTP self-host) | Yes (MIT, archived) | Yes (MIT) | Yes (MIT, archived) |\n\n## Security\n\n- **SSRF + LFI prevention** -- All `media_urls` and `reference_image_url` are validated at the dispatch boundary; only `http://` and `https://` schemes reach the providers. `file://`, `ftp://`, `gopher://`, and scheme-less URLs are rejected.\n- **No credentials in errors** -- Provider-side errors are sanitized before being returned.\n- **Degraded start** -- Missing credentials do not prevent the server from starting; affected actions surface actionable errors instead of crashing at boot.\n- **Credential storage** -- Credentials submitted through the browser credential form are stored encrypted via `mcp-core` (AES-GCM, machine-bound key) at `~/.imagine-mcp/config.json`.\n\n### Workspace username (HTTP setup form)\n\nThe browser credential form has an optional **workspace username** field. Entering\nthe same username always lands you in the same per-`sub` bucket, so your provider\nkeys stay reachable across a re-authorization and across devices, instead of being\ntied to the one-off subject minted for each `/authorize` round-trip. Leaving it\nblank keeps the previous per-authorize behaviour.\n\nTrust boundary: when the form is gated by a *shared* `MCP_RELAY_PASSWORD`, the\nusername is a partition key, not a secret -- anyone who knows that password can\ntype any username and reach that bucket. That is fine for a trusted group; an\nuntrusted multi-tenant deployment needs a per-user secret or delegated OAuth\ninstead.\n\n**One-time migration:** existing users must re-enter their credentials once after\nthis change. Nothing is deleted; credentials stored under the old random subject\nare simply no longer addressed.\n\n## Build from Source\n\n```bash\ngit clone https://github.com/n24q02m/imagine-mcp.git\ncd imagine-mcp\nmise run setup # or: uv sync --group dev\nmise run dev # run the server in stdio mode (add --http for the HTTP daemon)\n```\n\n## Deploy to Cloudflare\n\n[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/n24q02m/imagine-mcp)\n\nRun your own imagine instance serverless on Cloudflare (Worker + Container + KV). Storage\nis KV-only -- the per-user credential vault lives in KV, and generation returns base64 only\nbecause the container filesystem is ephemeral (`IMAGINE_OUTPUT_MODE=base64`).\n\n**Prerequisites:** a Cloudflare account on the **Workers Paid plan** -- required for Containers (the Cloudflare free tier does not include Containers) -- and the `wrangler` CLI.\n\n1. `git clone https://github.com/n24q02m/imagine-mcp && cd imagine-mcp`\n2. `wrangler login`\n3. Create the KV namespace (imagine is KV-only -- no D1 or Vectorize), then paste the\n returned id into `wrangler.jsonc` (the `` placeholder):\n ```\n wrangler kv namespace create imagine-kv\n ```\n4. Push the container image to your Cloudflare managed registry (CF Containers cannot pull\n from external registries directly), then set `` in `wrangler.jsonc`:\n ```\n docker pull ghcr.io/n24q02m/imagine-mcp:beta\n docker tag ghcr.io/n24q02m/imagine-mcp:beta imagine-mcp:beta\n wrangler containers push imagine-mcp:beta # prints registry.cloudflare.com//imagine-mcp:beta\n ```\n5. Point the remaining `wrangler.jsonc` placeholders at your own domain: ``\n (the `vars.PUBLIC_URL`, e.g. `https://imagine.example.com`) and ``\n (the `routes` custom-domain pattern, e.g. `imagine.example.com`).\n6. Set secrets. `CREDENTIAL_SECRET` (stable JWT signing key + per-user vault key) and\n `MCP_DCR_SERVER_SECRET` (proof of an intentional multi-user deploy) are required;\n `MCP_RELAY_PASSWORD` gates the browser setup form's login. Provider keys are optional\n server defaults -- users normally paste their own through the setup form instead:\n ```\n wrangler secret put CREDENTIAL_SECRET\n wrangler secret put MCP_DCR_SERVER_SECRET\n wrangler secret put MCP_RELAY_PASSWORD\n wrangler secret put GEMINI_API_KEY # optional provider default\n wrangler secret put OPENAI_API_KEY # optional provider default\n wrangler secret put XAI_API_KEY # optional provider default\n ```\n7. `wrangler deploy`, then open your Worker domain and finish setup in the browser relay form.\n\nThe `http` container image already runs multi-user (`MCP_TRANSPORT=http` is baked into the\nimage target). Storage maps to Cloudflare via `MCP_STORAGE_BACKEND=cf-kv` (encrypted\ncredential vault) with `IMAGINE_OUTPUT_MODE=base64`, which forces base64 responses so no\nmedia path is written to the ephemeral container filesystem.\n\n## Trust Model\n\nThis plugin implements **TC-Local** (machine-bound, single trust principal). See [mcp-core trust model](https://mcp.n24q02m.com/servers/mcp-core/trust-model/) for full classification.\n\n| Mode | Storage | Encryption | Who can read your data? |\n|---|---|---|---|\n| stdio (default) | `~/.imagine-mcp/config.json` | AES-GCM, machine-bound key | Only your OS user (file perm 0600) |\n| HTTP self-host | Same as stdio | Same | Only you (admin = user) |\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for the full development workflow, commit convention, and release process. Issues + Discussions welcome.\n\n## License\n\nApache-2.0 -- see [LICENSE](LICENSE).\n", "bytes": 19351, "sha": "6693942e39707eb09ddb2b84e1eec8309fe268a8ae74e7747b9ed577dd9c110c", "repo_slug": "n24q02m/imagine-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_n24q02m_imagine_mcp_00d2e528/readme" }