visualgen-mcp
visualgen-mcp is an MCP server that enables AI assistants like Claude Code to generate images and short videos using Google's Gemini API (Imagen 4 and Veo 3.1), saving results directly to a local project directory.
Generate Images (
generate_image): Create PNG images synchronously (~10s) using Gemini 2.5 Flash Image (nano-banana) or Imagen 4. Supports multiple aspect ratios and optional negative prompts (Imagen 4 only).Submit Video Jobs (
submit_video): Kick off asynchronous Veo 3.1 video generation with configurable model tiers (lite/fast/standard), aspect ratios, resolutions (720p–4K), negative prompts, and an optional starting image for image-to-video generation.Poll Video Status (
check_video): Check job status byjob_id; returns pending (with elapsed time), completed (with local file path and duration), or failed (with error). Automatically downloads the MP4 when ready.List Assets (
list_videos/list_images): View generated MP4s or PNGs in the output directory, sorted newest first, with paths, sizes, and timestamps.Get Pricing (
get_pricing): Retrieve current Gemini API rates (per-image and per-second) for all supported models to estimate costs before generation. Claude Code automatically prompts for confirmation on expensive operations (e.g., Veo standard, image-to-video).Configurable: Customize default model tiers, aspect ratios, output directories, and per-project overrides.
Integrates with Google's Gemini API to generate images using Imagen 4 and videos using Veo 3.1, providing AI-powered visual content creation capabilities.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@visualgen-mcp generate a hero image of a futuristic city skyline at dusk"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
visualgen-mcp
An MCP server that lets Claude Code generate images and short videos via Google's Gemini API (Imagen 4 for stills, Veo 3.1 for video).
Why this exists
I was building websites with Claude Code and kept hitting the same gap. Claude would design a great layout, then say "add your hero image here." I'd go generate one somewhere else, come back, wire it up, iterate, repeat. The context switching was the whole cost. So I built this MCP server to close the loop. Claude writes the prompt, the server hits Veo or Imagen, the file lands in the project directory, and Claude references it in the code it's already writing. One session, no handoffs.
I'm open-sourcing it because other people are solving the same problem, and nobody should have to build this twice.
Related MCP server: Gemini Image & Video Generation MCP
Demo
Claude Code generating visuals with visualgen-mcp and wiring them into the page.
https://github.com/user-attachments/assets/34d25755-cd4c-47b0-a0cb-056b9ed8b783
What it does
Six tools, exposed over stdio:
submit_video(prompt, model, aspect_ratio, resolution, negative_prompt?, image_path?)— submit a Veo 3.1 job. Returns ajob_idinstantly.check_video(job_id)— poll a job. When the video is ready, the server downloads it and returns the path.list_videos()— list MP4s in the output directory, newest first.generate_image(prompt, model, aspect_ratio, negative_prompt?)— synchronous image generation (typically under 10s). Returns the PNG path.list_images()— list PNGs in the output directory.get_pricing()— return current Gemini rates so Claude can warn you before expensive runs.
What it costs
Gemini API rates as of 2026-04-22. Verify at the official pricing page before production use.
Model | Cost |
Veo 3.1 Standard (720p / 1080p) | $0.40 / second |
Veo 3.1 Standard (4k) | $0.60 / second |
Veo 3.1 Fast (720p) | $0.10 / second |
Veo 3.1 Fast (1080p) | $0.12 / second |
Veo 3.1 Fast (4k) | $0.30 / second |
Veo 3.1 Lite (720p) | $0.05 / second |
Veo 3.1 Lite (1080p) | $0.08 / second |
Imagen 4 Fast | $0.02 / image |
Imagen 4 Standard | $0.04 / image |
Imagen 4 Ultra | $0.06 / image |
Gemini 2.5 Flash Image (Nano Banana) | $0.039 / image |
Install
For end users:
uvx visualgen-mcpFor contributors (from source):
git clone https://github.com/1RaghavM/visualgen-mcp.git
cd visualgen-mcp
uv sync
uv run python -m visualgen_mcpConfigure
Run the interactive setup once. It saves your profile to ~/.config/visualgen-mcp/config.toml (chmod 600) and optionally wires up .mcp.json in the current project directory.
uvx visualgen-mcp initYou'll be prompted for:
Gemini API key — get one at aistudio.google.com/apikey. Veo requires a paid plan; Imagen and Nano Banana work on the free tier but with stricter rate limits.
Output directory — where generated PNGs and MP4s land. Defaults to
~/visualgen-output. The server creates it if it doesn't exist, and tool responses return absolute paths so Claude can reference the files in the code it writes.Default video tier, image model, and aspect ratios — used when Claude calls a tool without specifying these.
Re-run visualgen-mcp init any time to update the profile. Per-project overrides still work: a GEMINI_API_KEY or OUTPUT_DIR set in a local .env file or in .mcp.json's env block takes precedence over the profile.
Use with Claude Code
Either run visualgen-mcp init inside your project (it offers to write this for you), or add this to .mcp.json at the root of your project:
{
"mcpServers": {
"visualgen": {
"command": "uvx",
"args": ["visualgen-mcp"]
}
}
}The server reads your API key and defaults from ~/.config/visualgen-mcp/config.toml. If you want to override them for a specific project, set GEMINI_API_KEY or OUTPUT_DIR in .mcp.json's env block — env vars take precedence over the profile.
Run /mcp inside Claude Code to confirm the server is connected. You should see visualgen listed with six tools.
The /visualgen skill
The server ships with a Claude Code skill that teaches Claude when to use each tool, how to structure prompts for common web-design asks, and when to confirm costs with you. If you ran visualgen-mcp init, it already offered to install it. Otherwise:
cd your-project
cp -r /path/to/visualgen-mcp/.claude/skills/visualgen ./.claude/skills/visualgenOnce installed, /visualgen hero video, modern SaaS landing, calm mood kicks off the whole pipeline in one shot — Claude picks the template, builds the prompt, submits the job, and wires the returned file into your code. You can also just ask for visuals in natural language — the skill auto-loads whenever Claude is about to call a visualgen-mcp tool.
The skill is opinionated about cost: Veo standard and any image-to-video call always ask you to confirm before spending. Everything else — all image generation plus Veo lite/fast text-to-video — proceeds silently.
Use with other MCP clients
Claude Desktop uses the same pattern. Add an entry under mcpServers in ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows). Any stdio-transport MCP client that supports tool calls works. There is no HTTP or auth layer — the server is intended for local use.
Example session
A real run from a landing-page project. Elided lines marked ....
> Build me a hero video loop for the top of the page. Something that suggests "city at night, calm, slow."
I'll generate that with the visualgen server.
submit_video(
prompt="A slow drone shot over a city skyline at night, warm window lights,
occasional headlights tracing streets below, calm mood, cinematic",
model="fast",
aspect_ratio="16:9",
resolution="1080p"
)
→ { "job_id": "f3c1...", "status": "submitted", "model": "veo-3.1-fast-generate-preview",
"estimated_seconds": 60 }
I'll check back in a minute.
check_video("f3c1...")
→ { "status": "pending", "elapsed_seconds": 25 }
... wait ...
check_video("f3c1...")
→ { "status": "complete",
"path": "/Users/.../landing/generated/veo-fast-20260422T191203Z.mp4",
"duration_seconds": 8.0 }
Writing it into the hero section:
Edit: src/components/Hero.tsx
<video
autoPlay
muted
loop
playsInline
className="absolute inset-0 h-full w-full object-cover"
src="/generated/veo-fast-20260422T191203Z.mp4"
/>One prompt, one generation, file in the project, code updated.
Tool reference
submit_video
Param | Type | Default | Notes |
|
| (required) | Video description. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Text describing what to avoid. |
|
|
| Absolute path to a PNG/JPEG/WebP starting frame. |
Returns {"job_id": str, "status": "submitted", "model": str, "estimated_seconds": int}.
check_video
Param | Type | Default |
|
| (required) |
Returns one of:
{"status": "pending", "elapsed_seconds": int}{"status": "complete", "path": str, "duration_seconds": float}{"status": "failed", "error": str}
list_videos
No parameters. Returns list[{"path": str, "size_bytes": int, "created_at": str}], newest first.
generate_image
Param | Type | Default | Notes |
|
| (required) | Image description. |
|
|
|
|
|
|
|
|
|
|
| Ignored by Nano Banana. |
Returns {"path": str, "model_used": str}.
list_images
No parameters. Returns list[{"path": str, "size_bytes": int, "created_at": str}], newest first.
get_pricing
No parameters. Returns a dict of current rates per model, a last_updated date, and a link to the source. Hardcoded — the server does not call an API for this.
Limits and gotchas
Veo clips are capped at 8 seconds. This server always requests 8 seconds.
There is no free tier for Veo. Every successful generation is billed.
Generated videos are deleted from Google's servers 48 hours after generation. Download them (via
check_video) within that window.The job store is in-memory. If you restart the server, pending jobs are lost. See the TODO in
src/visualgen_mcp/jobs.pyfor the SQLite migration path.Some prompts are rejected by Google's content filters. You get
{"status": "failed", ...}back, not a crash.Nano Banana (
gemini-2.5-flash-image) is faster and cheaper than Imagen 4 but does not accept anegative_prompt. Use Imagen 4 when you need one.list_videosandlist_imagesonly see files inOUTPUT_DIR. They do not recurse or cross directories.
Engineering decisions
Async video jobs. Veo generation takes tens of seconds, so
submit_videoreturns ajob_idimmediately andcheck_videopolls and downloads on completion, instead of blocking the MCP call.Files land in the project. Tools return absolute paths inside
OUTPUT_DIRso the agent can reference generated assets directly in the code it is writing.Profile + per-project overrides.
visualgen-mcp initwrites~/.config/visualgen-mcp/config.toml(chmod 600);GEMINI_API_KEY/OUTPUT_DIRin.envor.mcp.jsontake precedence.Cost awareness.
get_pricingreturns hardcoded rates, and the bundled/visualgenskill asks for confirmation before Veostandardor image-to-video calls.Local stdio only. No HTTP or auth layer; the server is intended for local MCP clients.
Testing
CI (.github/workflows/ci.yml) runs on Python 3.11 and 3.12:
uv sync --dev
uv run ruff check
uv run ruff format --check
uv run mypy src/
uv run pytest -qIntegration tests in tests/integration/ call the real Gemini API, cost money, and are not run in CI. See tests/integration/README.md.
Status
Implemented: the six MCP tools (Veo 3.1 video jobs, Imagen 4 / Nano Banana images, listing, pricing), the
initprofile wizard, and the/visualgenClaude Code skill.Experimental / limitations: the job store is in-memory (pending jobs are lost on restart); pricing is hardcoded as of 2026-04-22.
Planned: SQLite-backed job store (see the TODO in
src/visualgen_mcp/jobs.py).
Contributing
See CONTRIBUTING.md.
License
MIT. See LICENSE.
Available Tools
6 toolscheck_videoA
Check a video generation job. Downloads the file when ready.
Returns one of three shapes:
{"status": "pending", "elapsed_seconds": int}
{"status": "complete", "path": str, "duration_seconds": float}
{"status": "failed", "error": str}
Safe to call repeatedly. Once a job is complete or failed, subsequent calls return the cached terminal state without re-polling.
Args: job_id: The id returned by submit_video.
Inputs: job_id (required). Returns: object
generate_imageA
Generate an image synchronously. Blocks until the file is on disk.
Typical latency is under 10 seconds. The PNG is written to the configured OUTPUT_DIR and the absolute path is returned.
Args: prompt: Text description of the image to generate. model: "nano-banana" (Gemini 2.5 Flash Image, the default — cheapest and fastest) or "imagen" (Imagen 4, higher quality, higher cost). aspect_ratio: "1:1", "16:9", "9:16", "4:3", or "3:4". negative_prompt: Optional text describing what to avoid. Ignored by Nano Banana; used by Imagen 4 when supplied.
Inputs: prompt (required), model, aspect_ratio, negative_prompt. Returns: object
get_pricingA
Return current published Gemini API pricing for the models this server uses.
Rates are per-image for images and per-second for video. Pricing is
hardcoded from the official docs (see the source field) and may drift;
always verify before expensive operations.
Inputs: no named parameters. Returns: object
list_imagesA
List every PNG file in the configured OUTPUT_DIR, newest first.
Each entry has absolute path, size in bytes, and creation timestamp.
Inputs: no named parameters. Returns: result
list_videosA
List every MP4 file in the configured OUTPUT_DIR, newest first.
Each entry has absolute path, size in bytes, and creation timestamp.
Inputs: no named parameters. Returns: result
submit_videoA
Submit a Veo 3.1 video generation job. Returns immediately with a job_id.
Videos typically take 30-120 seconds. Call check_video(job_id) to poll for completion. The final MP4 is written to the configured OUTPUT_DIR and its absolute path is returned by check_video once ready.
Args: prompt: Text description of the video to generate. model: "lite" (cheapest), "fast" (default, good balance), or "standard" (highest quality, most expensive). See get_pricing for rates. aspect_ratio: "16:9" (landscape) or "9:16" (portrait). resolution: "720p", "1080p", or "4k". "4k" is rejected for model="lite". negative_prompt: Optional text describing what to avoid. image_path: Optional absolute path to a PNG/JPEG/WebP file to use as the starting frame for image-to-video generation.
Inputs: prompt (required), model, aspect_ratio, resolution, +2 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool has a clearly distinct purpose with no ambiguity. check_video monitors video jobs, generate_image creates images, get_pricing provides cost information, list_images and list_videos enumerate outputs, and submit_video initiates video generation. The separation between image and video operations is particularly clear.
All tools follow a consistent verb_noun pattern with snake_case throughout. The naming is predictable and readable: check_video, generate_image, get_pricing, list_images, list_videos, and submit_video. This consistency makes the tool set easy to understand at a glance.
Six tools is well-scoped for a visual generation server. This provides complete coverage for both image and video workflows without being overwhelming. Each tool earns its place by addressing a specific need in the generation, monitoring, listing, or pricing aspects of the service.
The tool set covers the core visual generation domain comprehensively with create, check, and list operations for both images and videos, plus pricing information. The only minor gap is the lack of a tool to delete or manage generated files, but agents can work around this using system file operations.
Maintenance
Related MCP Connectors
MCP server for Google Veo AI video generation
Use AI models for chat, image, and video generation from Claude Code and other MCP hosts.
MCP server for Qwen Image 3 AI image generation
MCP server for Grok Imagine AI video generation
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server that brings Google Gemini's image generation and editing capabilities to Claude Desktop, Claude Code, and Cursor. It supports 2K image creation, natural language image transformations, and session consistency to maintain styles across generations.7MIT
- AlicenseBqualityDmaintenanceA production-ready MCP server that enables Claude and other LLMs to generate images and videos using Google's Gemini AI models (Gemini 2.0 Flash and Veo 2.0).33ISC
- AlicenseAqualityDmaintenanceAn MCP server that provides access to Google Gemini models via Vertex AI, enabling text generation, multi-turn chat, image/video generation, and frontend design through Claude Code.21MIT
- AlicenseNot gradedqualityDmaintenanceMCP server that enables Claude Code to generate images using Google's Gemini image generation models.MIT