Google Veo and Gemini image MCP server

Generate videos with Google Veo and images with Gemini. The package name remains mcp-video-generation-veo2 for existing installations; version 2 uses maintained, configurable models and MCP SDK 2.

Install and run

Use Node.js 22 or 24. From this repository:

npm ci
npm run build
node dist/index.js

For an MCP host, launch node directly with the absolute dist/index.js path. Do not launch npm start as the stdio child: npm's own banners can corrupt the JSON-RPC stream. The installed package also provides mcp-video-generation-veo2.

{
  "mcpServers": {
    "veo": {
      "command": "node",
      "args": ["/absolute/path/mcp-veo2/dist/index.js"],
      "env": {
        "GOOGLE_API_KEY": "YOUR_GOOGLE_API_KEY",
        "VIDEO_MODEL": "veo-3.1-generate-preview",
        "IMAGE_MODEL": "gemini-3.1-flash-image"
      }
    }
  }
}

An API key is needed only for generation; discovery, templates, and saved-media access work without one. Google model access, billing and quota must be enabled. Generation may incur charges even if the MCP request is cancelled or times out. The server never automatically retries a paid creation request.

HTTP and existing SSE clients

Set MCP_AUTH_TOKEN to a random value of at least 24 characters, then run:

node dist/index.js http

Open http://127.0.0.1:3000/ for the included browser connection check. It asks for the MCP token, keeps it in memory, and lists saved media using real MCP requests.

• /mcp: MCP 2026-07-28 and stateless legacy Streamable HTTP.
• /sse plus /messages?sessionId=...: legacy SSE compatibility for existing clients such as LibreChat. Each connection owns its own MCP server; request bodies are parsed once. SSE sessions expire after 10 minutes without a POST.
• node dist/index.js sse remains an alias for the same HTTP listener.
• Send Authorization: Bearer <MCP_AUTH_TOKEN> on every MCP request, including the initial SSE GET. The Google API key is a separate, server-only credential.

The default bind address is loopback. To expose the service, configure HOST, ALLOWED_HOSTS and ALLOWED_ORIGINS for the proxy deployment and terminate TLS at that proxy. Only exact configured Host values and browser origins are trusted. Each deployment and storage directory belongs to one operator; do not share its bearer token/storage across untrusted tenants. This is static bearer deployment authentication, not a complete OAuth authorization server.

Issue #5's file:// frontend and /sse/tool/listGeneratedVideos URL were never an MCP REST API. Use the included page or an MCP client. Opaque Origin: null and hostile origins are rejected; no wildcard CORS is enabled. The old public /videos directory server has been removed.

Tools and media

All seven tool names are retained:

Tool	Inputs
generateVideoFromText	prompt, optional video settings
generateVideoFromImage	image, optional prompt and video settings
generateImage	prompt, optional includeFullData
generateVideoFromGeneratedImage	prompt, optional videoPrompt and video settings
listGeneratedVideos	No inputs
listGeneratedImages	No inputs
getImage	Saved image UUID, optional includeFullData

Settings are flat tool arguments, for example:

{
  "prompt": "A slow camera pan through a sunlit forest",
  "aspectRatio": "16:9",
  "durationSeconds": 8,
  "resolution": "720p"
}

Veo 3.1 accepts durations 4, 6, or 8 seconds; 1080p/4k requires 8 seconds. Text generation uses personGeneration=allow_all; image animation uses allow_adult, subject to Google's regional restrictions and filtering. One video/image is generated per call. Explicit unsupported settings fail before provider generation.

An image input can be a base64 string, an MCP image object { "type": "image", "mimeType": "image/png", "data": "..." }, an allowed HTTPS URL, or an absolute file path beneath IMAGE_INPUT_DIR. PNG, JPEG and WebP are checked by MIME type and file signature. Input images are limited to 10 MiB. URL imports require an explicit IMAGE_URL_HOSTS allowlist controlled by the operator; redirects must remain in that allowlist. Do not allow hosts you do not trust.

Outputs contain metadata and videos://<uuid> or images://<uuid> resource links. Resources return actual media blobs; video data is never mislabeled as an MCP image. includeFullData=true additionally embeds media in the tool result, limited to 8 MiB. Resources are likewise limited to 8 MiB for interoperability. Larger assets remain in STORAGE_DIR for the operator to retrieve on the server.

Video downloads always run on the server. API keys are sent in headers, never in returned or saved URLs. Redirects are bounded; cross-host redirects do not receive the Google key. Downloaded bytes, metadata and API responses have size limits. Provider error bodies and raw request arguments are not logged. Startup rewrites valid historical metadata through an allowlist, dropping old key-bearing URLs and absolute paths while preserving media files. Rotate keys previously exposed by an older release and remove historical copies from any downstream logs/backups.

Configuration

Copy .env.example or set environment variables:

Variable	Default / meaning
GOOGLE_API_KEY	Provider key; GEMINI_API_KEY is an alias
VIDEO_MODEL	veo-3.1-generate-preview
IMAGE_MODEL	gemini-3.1-flash-image
STORAGE_DIR	./generated-videos; images in its images subdirectory
HOST, PORT	127.0.0.1, 3000
MCP_AUTH_TOKEN	Required for HTTP/SSE, at least 24 characters
ALLOWED_HOSTS	Additional comma-separated exact host[:port] values
ALLOWED_ORIGINS	Additional comma-separated exact HTTP(S) origins
IMAGE_INPUT_DIR	STORAGE_DIR/images; real paths must remain beneath it
IMAGE_URL_HOSTS	Empty; comma-separated trusted HTTPS source hosts
GENERATION_TIMEOUT_MS	600000, maximum 1800000
POLL_INTERVAL_MS	10000
MAX_MEDIA_BYTES	67108864; maximum 134217728

Veo 2, Imagen 3 and Imagen 4 are not suitable defaults for the end of 2026. Google's Veo guide documents the current video interface; image generation lists current Gemini image models. This implementation uses the supported generateContent image API; Google's Interactions overview confirms it remains supported. Recheck model availability and deprecations before deployment. Configurable model IDs permit compatible replacements; they do not guarantee that a future model accepts the same parameters. Veo 3.1's current identifier is a preview, so end-of-2026 availability cannot be promised.

Version 2 migration

• MCP stdio and HTTP serve revision 2026-07-28 through SDK2's actual serveStdio / createMcpHandler entries. Legacy stdio/HTTP/SSE remains tested.
• Duration 5/7, numberOfVideos=2, numberOfImages>1, unsupported person modes, enhancePrompt=true, and autoDownload=false now fail explicitly.
• Media always downloads locally, and public storage directory access is removed.
• Use direct Node/package binary for MCP stdio. Missing generation credentials no longer prevent listing tools.
• Unsupported resource subscriptions are not advertised.

Verification

npm run check

Tests use credential-free provider fixtures and actual stdio, Streamable HTTP, legacy SSE and production-only packed installs. They cover schema errors, cancellation, key handling, redirects, size limits, media types, path boundaries, connection isolation, Host/Origin/auth checks, and clean EOF. CI runs on Node 22 and 24. No paid generation is performed in automated tests; a live account test is still required to establish provider billing, regional access and visual quality.

MIT license. Original examples remain in example-files/.