MCP 服务器

imagine-mcp

Production-grade MCP server for image and video understanding and generation across Gemini, OpenAI, and Grok.

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.

<details> <summary><strong>Sister projects from n24q02m</strong> (click to expand)</summary>

Project	Tagline	Tag
better-code-review-graph	Knowledge graph for token-efficient code reviews -- fixed search, configurabl...	MCP
better-email-mcp	IMAP/SMTP email server for AI agents -- 6 composite tools with multi-account ...	MCP
better-godot-mcp	Composite MCP server for Godot Engine -- 17 mega-tools for AI-assisted game d...	MCP
better-notion-mcp	Markdown-first Notion API server for AI agents -- 10 composite tools replacin...	MCP
better-telegram-mcp	MCP server for Telegram with dual-mode support: Bot API (httpx) for quick bot...	MCP
claude-plugins	Full documentation: mcp.n24q02m.com — unified docs for all 8 servers + the mc...	Marketplace
imagine-mcp	Production-grade MCP server for image and video understanding + generation ac...	MCP
jules-task-archiver	Chrome Extension for bulk operations on Jules tasks via batchexecute API -- a...	Tooling
mcp-core	Unified MCP Streamable HTTP 2025-11-25 transport, OAuth 2.1 Authorization Ser...	MCP
mnemo-mcp	Persistent AI memory with hybrid search and embedded sync. Open, free, unlimi...	MCP
qwen3-embed	Lightweight Qwen3 text embedding and reranking via ONNX Runtime and GGUF	Library
skret	Secrets without the server.	CLI
web-core	Shared web infrastructure package for search, scraping, HTTP security, and st...	Library
wet-mcp	Open-source MCP Server for web search, content extraction, library docs & mul...	MCP

</details>

Features
Status
Documentation
Tools
Security
Build from Source
Trust Model
Contributing
License

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
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
Dual transport -- pure stdio with provider env vars (default) or HTTP multi-user with paste-token relay form

Status

2026-05-02 -- Architecture stabilization update

Past months saw significant churn around credential handling and the daemon-bridge auto-spawn pattern. This caused multi-process races, browser tab spam, and inconsistent setup UX across plugins. As of v<auto>, the architecture is stable: 2 clean modes (stdio + HTTP), no daemon-bridge layer, no auto-spawn from stdio.

Apologies for the instability period. If you encountered issues with prior versions, please update to v<auto>+ and follow the current Setup docs -- most prior workarounds are no longer needed.

Related plugins from the same author:

wet-mcp -- Web search + content extraction

mnemo-mcp -- Persistent AI memory

better-notion-mcp -- Notion API

better-email-mcp -- Email management

better-telegram-mcp -- Telegram

better-godot-mcp -- Godot Engine

better-code-review-graph -- Code review knowledge graph

All plugins share the same architecture -- install once, learn pattern transfers.

Documentation

Full docs at mcp.n24q02m.com/servers/imagine-mcp/:

Setup -- install methods for Claude Code, Codex, Gemini CLI, Cursor, Windsurf, mcp.json
Modes overview -- stdio / local-relay / remote-relay / remote-oauth
Multi-user setup -- per-JWT-sub credential model

Install with AI agent -- paste this to your AI coding agent:

Install MCP server imagine-mcp following the steps at
https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/imagine-mcp/setup-with-agent.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 (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

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

Trust Model

This plugin implements TC-Local (machine-bound, single trust principal). See mcp-core/docs/TRUST-MODEL.md for full classification.

Mode	Storage	Encryption	Who can read your data?
stdio (default)	`~/.imagine-mcp/config.json`	AES-GCM, machine-bound key	Only your OS user (file perm 0600)
HTTP self-host	Same as stdio	Same	Only you (admin = user)