https://github.com/n24q02m/imagine-mcp
MCP server for image/video understanding + generation across Gemini, OpenAI, Grok (N+2 layout; leaderboard-ranked models; weekly refresh)
https://github.com/n24q02m/imagine-mcp
antigravity claude codex copilot cursor gemini gemini-cli grok image-generation image-understanding mcp mcp-server model-context-protocol openai opencode video-generation
Last synced: about 1 month ago
JSON representation
MCP server for image/video understanding + generation across Gemini, OpenAI, Grok (N+2 layout; leaderboard-ranked models; weekly refresh)
- Host: GitHub
- URL: https://github.com/n24q02m/imagine-mcp
- Owner: n24q02m
- License: mit
- Created: 2026-04-17T08:12:31.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-24T08:21:34.000Z (about 1 month ago)
- Last Synced: 2026-04-24T09:28:44.911Z (about 1 month ago)
- Topics: antigravity, claude, codex, copilot, cursor, gemini, gemini-cli, grok, image-generation, image-understanding, mcp, mcp-server, model-context-protocol, openai, opencode, video-generation
- Language: Python
- Homepage: https://pypi.org/project/imagine-mcp/
- Size: 208 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# imagine-mcp
mcp-name: io.github.n24q02m/imagine-mcp
**Production-grade MCP server for image and video understanding + generation across Gemini, OpenAI, and Grok.**
[](https://github.com/n24q02m/imagine-mcp/actions/workflows/ci.yml)
[](https://codecov.io/gh/n24q02m/imagine-mcp)
[](https://pypi.org/project/imagine-mcp/)
[](https://hub.docker.com/r/n24q02m/imagine-mcp)
[](LICENSE)
[](#)
[](#)
[](#)
[](https://github.com/python-semantic-release/python-semantic-release)
[](https://developer.mend.io/)
## Features
- **Multimodal understanding** -- Describe, classify, or reason over images and videos (Gemini handles mixed image + video in one call)
- **Image generation** -- Text-to-image and image-to-image (edit / inpaint) across Gemini Imagen, OpenAI gpt-image, Grok Imagine
- **Video generation** -- Text-to-video and image-to-video (Gemini Veo 3.1, Grok Imagine Video)
- **3 providers x 2 tiers** -- Same interface for `gemini` / `openai` / `grok` at `poor` (cheap/fast) or `rich` (high quality); swap via parameter
- **Leaderboard-ranked models** -- Provider ordering auto-refreshed weekly from Artificial Analysis + LMArena leaderboards
- **Zero-config onboarding** -- Browser-based credential relay form; no `.env` files or manual credential plumbing
- **Degraded mode** -- Server starts with zero credentials and surfaces remaining providers as you add keys
- **Response cache** -- Disk-based caching of `understand` responses with configurable TTL
- **Smart stdio proxy** -- stdio transport spawns a local HTTP daemon and forwards JSON-RPC frames, sharing credentials across invocations
## Setup
**With AI Agent** -- copy and send this to your AI agent:
> Please set up imagine-mcp for me. Follow this guide:
> https://raw.githubusercontent.com/n24q02m/imagine-mcp/main/docs/setup-with-agent.md
**Manual setup** -- follow [docs/setup-manual.md](docs/setup-manual.md)
## Tools
| Tool | Actions | Description |
|:-----|:--------|:------------|
| `understand` | -- | Describe or reason over one or more image/video URLs. `media_urls: list[str]`, `prompt: str`, `provider`, `tier`, `max_tokens`. |
| `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`. |
| `config` | `open_relay`, `relay_status`, `relay_skip`, `relay_reset`, `relay_complete`, `warmup`, `status`, `set`, `cache_clear` | Credential + runtime config: open relay form, check credential state, set runtime knobs (log level, default provider, TTL), clear response cache. |
| `help` | -- | Full Markdown documentation for `understand`, `generate`, or `config` topics. |
Model IDs per provider x action x tier are leaderboard-ranked; see [`docs/models.md`](docs/models.md) (auto-regenerated from `src/imagine_mcp/models.py`).
## Security
- **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.
- **No credentials in errors** -- Provider-side errors are sanitized before being returned.
- **Degraded start** -- Missing credentials do not prevent the server from starting; affected actions surface actionable errors instead of crashing at boot.
- **Relay transport** -- Credentials submitted through the local relay form are stored encrypted via `mcp-core` (`config.enc`, user-scoped `platformdirs`).
## Build from Source
```bash
git clone https://github.com/n24q02m/imagine-mcp.git
cd imagine-mcp
mise run setup # or: uv sync --group dev
mise run dev # run http local relay daemon
```
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development workflow, commit convention, and release process. Issues + Discussions welcome.
## License
MIT -- see [LICENSE](LICENSE).