一个 MCP 服务器，允许 Claude Code 通过 Google 的 Gemini API（Imagen 4 用于静态图像，Veo 3.1 用于视频）生成图像和短视频。
我在使用 Claude Code 构建网站时，总是遇到同样的问题。Claude 会设计出很棒的布局，然后说“在这里添加你的主图”。我得去别的地方生成一张，回来，连接好，迭代，重复。上下文切换是最大的成本。所以我构建了这个 MCP 服务器来闭环。Claude 编写提示词，服务器调用 Veo 或 Imagen，文件落入项目目录，Claude 在它正在编写的代码中引用它。一次会话，无需交接。
我将其开源是因为其他人也在解决同样的问题，没人应该重复造轮子。
Related MCP server: Gemini Image & Video Generation MCP
Claude Code 使用 visualgen-mcp 生成视觉效果并将其连接到页面中。
https://github.com/user-attachments/assets/34d25755-cd4c-47b0-a0cb-056b9ed8b783
通过 stdio 公开的六个工具：
submit_video(prompt, model, aspect_ratio, resolution, negative_prompt?, image_path?) — 提交 Veo 3.1 任务。立即返回 job_id。
check_video(job_id) — 轮询任务。当视频准备好后，服务器会下载它并返回路径。
list_videos() — 列出输出目录中的 MP4 文件，按最新排序。
generate_image(prompt, model, aspect_ratio, negative_prompt?) — 同步图像生成（通常在 10 秒内）。返回 PNG 路径。
list_images() — 列出输出目录中的 PNG 文件。
get_pricing() — 返回当前的 Gemini 费率，以便 Claude 在昂贵的运行前提醒你。
截至 2026-04-22 的 Gemini API 费率。在生产环境使用前，请在官方定价页面核实。
模型 | 费用 |
Veo 3.1 Standard (720p / 1080p) | $0.40 / 秒 |
Veo 3.1 Standard (4k) | $0.60 / 秒 |
Veo 3.1 Fast (720p) | $0.10 / 秒 |
Veo 3.1 Fast (1080p) | $0.12 / 秒 |
Veo 3.1 Fast (4k) | $0.30 / 秒 |
Veo 3.1 Lite (720p) | $0.05 / 秒 |
Veo 3.1 Lite (1080p) | $0.08 / 秒 |
Imagen 4 Fast | $0.02 / 图像 |
Imagen 4 Standard | $0.04 / 图像 |
Imagen 4 Ultra | $0.06 / 图像 |
Gemini 2.5 Flash Image (Nano Banana) | $0.039 / 图像 |
对于最终用户：
uvx visualgen-mcp对于贡献者（从源码安装）：
git clone https://github.com/1RaghavM/visualgen-mcp.git
cd visualgen-mcp
uv sync
uv run python -m visualgen_mcp运行一次交互式设置。它会将你的配置文件保存到 ~/.config/visualgen-mcp/config.toml (chmod 600)，并可选择在当前项目目录中配置 .mcp.json。
uvx visualgen-mcp init系统会提示你输入：
Gemini API key — 在 aistudio.google.com/apikey 获取。Veo 需要付费计划；Imagen 和 Nano Banana 可在免费层级使用，但有更严格的速率限制。
输出目录 — 生成的 PNG 和 MP4 存放的位置。默认为 ~/visualgen-output。如果目录不存在，服务器会自动创建，工具响应会返回绝对路径，以便 Claude 在代码中引用这些文件。
默认视频层级、图像模型和宽高比 — 当 Claude 调用工具而未指定这些参数时使用。
随时重新运行 visualgen-mcp init 以更新配置。每个项目的覆盖设置仍然有效：在本地 .env 文件或 .mcp.json 的 env 块中设置的 GEMINI_API_KEY 或 OUTPUT_DIR 优先于全局配置。
在你的项目内运行 visualgen-mcp init（它会提示为你写入配置），或者在项目根目录的 .mcp.json 中添加以下内容：
{
"mcpServers": {
"visualgen": {
"command": "uvx",
"args": ["visualgen-mcp"]
}
}
}服务器会从 ~/.config/visualgen-mcp/config.toml 读取你的 API 密钥和默认设置。如果你想为特定项目覆盖它们，请在 .mcp.json 的 env 块中设置 GEMINI_API_KEY 或 OUTPUT_DIR — 环境变量优先于配置文件。
在 Claude Code 中运行 /mcp 以确认服务器已连接。你应该能看到 visualgen 列出了六个工具。
/visualgen 技能该服务器附带一个 Claude Code 技能，它会教 Claude 何时使用每个工具、如何为常见的网页设计需求构建提示词，以及何时与你确认费用。如果你运行了 visualgen-mcp init，它已经提示过安装此技能。否则：
cd your-project
cp -r /path/to/visualgen-mcp/.claude/skills/visualgen ./.claude/skills/visualgen安装后，使用 /visualgen hero video, modern SaaS landing, calm mood 可以一次性启动整个流程 — Claude 会选择模板、构建提示词、提交任务并将返回的文件连接到你的代码中。你也可以直接用自然语言要求生成视觉效果 — 只要 Claude 即将调用 visualgen-mcp 工具，该技能就会自动加载。
该技能对费用有明确的判断：Veo standard 和任何图生视频调用在执行前总是会要求你确认。其他所有操作（所有图像生成以及 Veo lite/fast 文生视频）都会静默进行。
Claude Desktop 使用相同的模式。在 ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 或 %APPDATA%\Claude\claude_desktop_config.json (Windows) 中的 mcpServers 下添加条目。任何支持工具调用的 stdio 传输 MCP 客户端都可以使用。没有 HTTP 或认证层 — 该服务器旨在本地使用。
来自落地页项目的真实运行记录。省略行标记为 ...。
> 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"
/>一个提示词，一次生成，文件进入项目，代码已更新。
submit_video参数 | 类型 | 默认值 | 说明 |
|
| (必填) | 视频描述。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 描述要避免的内容。 |
|
|
| PNG/JPEG/WebP 起始帧的绝对路径。 |
返回 {"job_id": str, "status": "submitted", "model": str, "estimated_seconds": int}。
check_video参数 | 类型 | 默认值 |
|
| (必填) |
返回以下之一：
{"status": "pending", "elapsed_seconds": int}
{"status": "complete", "path": str, "duration_seconds": float}
{"status": "failed", "error": str}
list_videos无参数。返回 list[{"path": str, "size_bytes": int, "created_at": str}]，按最新排序。
generate_image参数 | 类型 | 默认值 | 说明 |
|
| (必填) | 图像描述。 |
|
|
|
|
|
|
|
|
|
|
| Nano Banana 会忽略此项。 |
返回 {"path": str, "model_used": str}。
list_images无参数。返回 list[{"path": str, "size_bytes": int, "created_at": str}]，按最新排序。
get_pricing无参数。返回包含每个模型当前费率、last_updated 日期和来源链接的字典。硬编码 — 服务器不会为此调用 API。
Veo 剪辑限制为 8 秒。此服务器始终请求 8 秒。
Veo 没有免费层级。每次成功生成都会计费。
生成的视频在生成 48 小时后会从 Google 服务器删除。请在此窗口内下载（通过 check_video）。
任务存储在内存中。如果你重启服务器，挂起的任务会丢失。请参阅 src/visualgen_mcp/jobs.py 中的 TODO 以了解 SQLite 迁移路径。
某些提示词会被 Google 的内容过滤器拒绝。你会收到 {"status": "failed", ...}，而不是崩溃。
Nano Banana (gemini-2.5-flash-image) 比 Imagen 4 更快、更便宜，但不接受 negative_prompt。需要时请使用 Imagen 4。
list_videos 和 list_images 仅查看 OUTPUT_DIR 中的文件。它们不会递归或跨目录查找。
请参阅 CONTRIBUTING.md。
MIT。请参阅 LICENSE。
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.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure and excels. It reveals key traits: polling behavior ('Downloads the file when ready'), idempotency ('Safe to call repeatedly'), caching ('returns the cached terminal state'), and the three possible return shapes with their semantics. This goes well beyond basic parameter documentation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly structured and concise. It front-loads the core purpose, then details return shapes, behavioral notes, and parameters in logical order. Every sentence earns its place with essential information, and there is no wasted verbiage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (stateful job monitoring), lack of annotations, and presence of an output schema (which covers return values), the description is complete. It explains the tool's role in a workflow, behavioral guarantees, parameter semantics, and output interpretation, leaving no significant gaps for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description must compensate. It adds crucial semantic context for the single parameter: 'job_id: The id returned by submit_video' clarifies the parameter's origin and relationship to another tool. However, it doesn't specify format constraints (e.g., UUID, string length) that might be in an unannotated schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('Check', 'Downloads') and resource ('video generation job'), distinguishing it from siblings like 'submit_video' (which creates jobs) and 'list_videos' (which lists existing videos). It explicitly describes the monitoring and file retrieval functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool: 'Check a video generation job' implies it's for monitoring jobs created by 'submit_video'. It also specifies 'Safe to call repeatedly' and explains terminal state behavior, giving clear operational context without misleading exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | ||
| model | No | nano-banana | |
| aspect_ratio | No | 16:9 | |
| negative_prompt | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: synchronous operation ('Blocks until the file is on disk'), typical latency ('under 10 seconds'), file handling ('PNG is written to OUTPUT_DIR'), and return value ('absolute path is returned'). It also notes model-specific behavior differences (e.g., negative_prompt ignored by Nano Banana). However, it lacks details on error handling or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded: the first sentence states the core purpose and key behavioral trait (synchronous blocking). Subsequent sentences efficiently cover latency, output details, and parameter explanations in a structured format with bullet-like clarity. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (image generation with multiple parameters), no annotations, and the presence of an output schema (which handles return value documentation), the description is complete enough. It covers purpose, behavior, parameters, and output location, leaving the output schema to detail the return structure. No critical gaps remain for agent understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully compensate. It provides comprehensive parameter semantics: 'prompt' as the text description, 'model' with two options and cost/quality trade-offs, 'aspect_ratio' with five specific options, and 'negative_prompt' with optional usage and model-specific behavior. This adds significant meaning beyond the bare schema, fully documenting all four parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Generate an image synchronously' with specific details about the output format (PNG) and location (OUTPUT_DIR). It distinguishes from sibling tools like 'list_images' (which retrieves existing images) and 'submit_video' (which handles video generation), making the verb+resource combination specific and differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: for synchronous image generation with latency under 10 seconds. It distinguishes from alternatives by specifying the output format (PNG) and location (OUTPUT_DIR), but does not explicitly state when NOT to use it or compare it to other image-related tools beyond the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key traits: it returns 'current published' pricing, notes that rates vary by media type (images vs. video), mentions the data source ('hardcoded from the official docs'), and warns about potential drift and the need for verification. This covers most behavioral aspects for a read-only pricing tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose in the first sentence, followed by supporting details. Every sentence earns its place by clarifying pricing units, data source, and reliability warnings. It is appropriately sized with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, no annotations, but with an output schema), the description is complete. It covers purpose, usage context, behavioral details like data source and limitations, and output semantics. The presence of an output schema means the description doesn't need to explain return values, so this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description adds value by explaining the semantics of the returned pricing data (e.g., 'per-image for images and per-second for video'), which goes beyond the schema. A baseline of 4 is appropriate for zero-parameter tools with high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Return current published Gemini API pricing for the models this server uses.' It specifies the verb ('Return'), resource ('Gemini API pricing'), and scope ('models this server uses'), distinguishing it from sibling tools like generate_image or submit_video that perform different operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: to get pricing information for API operations. It implies usage before 'expensive operations' but does not explicitly state when not to use it or name alternatives among sibling tools, which would be needed for a score of 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every PNG file in the configured OUTPUT_DIR, newest first.
Each entry has absolute path, size in bytes, and creation timestamp.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does well by disclosing key behavioral traits: it lists files from a specific directory (OUTPUT_DIR), sorts them (newest first), and describes the return format (absolute path, size, creation timestamp). It doesn't mention permissions, rate limits, or error conditions, but covers the core behavior adequately.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise with two sentences that each earn their place. The first sentence states the core action and scope, while the second provides essential output details. No wasted words, well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, no annotations, but has output schema), the description is complete enough. It explains what the tool does, how results are sorted, and what data each entry contains. The output schema will handle return value details, so the description doesn't need to explain return values further.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters with 100% schema description coverage, so the baseline is 4. The description doesn't need to add parameter information, and it appropriately focuses on the tool's behavior rather than parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('List every PNG file') and resources ('in the configured OUTPUT_DIR'), including sorting order ('newest first'). It distinguishes from sibling tools like 'list_videos' by specifying PNG files rather than videos.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (listing PNG files in OUTPUT_DIR), but doesn't explicitly state when not to use it or name alternatives. It implies usage for PNG files specifically, which helps differentiate from 'list_videos' for video files.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every MP4 file in the configured OUTPUT_DIR, newest first.
Each entry has absolute path, size in bytes, and creation timestamp.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does well by disclosing key behavioral traits: it lists files 'newest first', specifies the exact fields in each entry (path, size, timestamp), and mentions the configured OUTPUT_DIR as the source. It lacks details on permissions or error handling, but covers core behavior adequately.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise and front-loaded: the first sentence states the core purpose and key details (MP4 files, OUTPUT_DIR, ordering), and the second sentence adds essential output structure. Every sentence earns its place with zero waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (0 parameters, simple list operation), no annotations, and the presence of an output schema (which handles return values), the description is complete enough. It covers purpose, behavior, and output fields, leaving no significant gaps for this context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters with 100% schema description coverage, so the baseline is 4. The description adds no parameter information, which is appropriate since there are no parameters to document, maintaining clarity without redundancy.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('List every MP4 file') and resource ('in the configured OUTPUT_DIR'), with explicit scope details. It distinguishes from sibling tools like 'list_images' by specifying MP4 files only, not images.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context about when to use this tool (to list MP4 files in OUTPUT_DIR), but does not explicitly state when not to use it or name alternatives like 'list_images' for non-MP4 files or 'check_video' for individual video inspection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | ||
| model | No | fast | |
| aspect_ratio | No | 16:9 | |
| resolution | No | 720p | |
| negative_prompt | No | ||
| image_path | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: the asynchronous nature (returns immediately with job_id), typical processing time (30-120 seconds), polling mechanism (call check_video), output location (written to OUTPUT_DIR), and format (MP4). This covers execution flow, timing, and output handling beyond basic functionality.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and well-structured: it starts with the core purpose and immediate return, then explains the asynchronous workflow, and finally details each parameter in a clear Args section. Every sentence adds value without redundancy, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of an asynchronous video generation tool with 6 parameters, no annotations, and an output schema (implied by 'Returns immediately with a job_id'), the description is complete. It covers the tool's purpose, behavioral workflow, parameter semantics, and integration with sibling tools, providing all necessary context for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully compensate. It provides detailed semantic explanations for all 6 parameters: purpose of prompt, model options with cost/quality trade-offs, aspect ratio meanings, resolution options with constraints (4k rejected for lite), optional negative_prompt usage, and image_path for image-to-video. This adds substantial meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Submit a Veo 3.1 video generation job') and resource ('video'), distinguishing it from siblings like check_video (polling), generate_image (image creation), and list_videos (listing). It uses precise verbs and identifies the exact resource being created.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (to start a video generation job) and explicitly mentions check_video as the follow-up for polling completion. However, it doesn't explicitly state when NOT to use it or compare it to alternatives like generate_image for image generation, leaving some sibling differentiation implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0check_videogenerate_imageget_pricinglist_imageslist_videossubmit_videoScored 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.
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
