Agnes AI MCP Server
The Agnes AI MCP Server provides free text-to-image and text-to-video generation via the Agnes AI API, with automatic local downloads to ~/agnes_output.
text_to_image: Generate 1β4 images from a text prompt using
agnes-image-2.0-flashoragnes-image-2.1-flashmodels, with optional reference images for composition and configurable output size.image_to_image: Transform existing images by providing one or more reference image URLs combined with a text prompt (batch up to 4 images).
text_to_video: Generate videos from a text prompt (and optionally images), with control over resolution (up to 1080p), frame count (up to ~18s), frame rate, inference steps, and seed.
image_to_video: Animate a static image into a video by providing an image URL or base64 Data URI and a prompt describing the desired motion.
keyframe_animation: Create a smooth video transition between 2 or more keyframe images, guided by a text prompt.
check_video_status: Poll the status of an asynchronous video generation task using a
video_idortask_id, retrieving progress, URL, and metadata.
All features are completely free ($0 per image, $0 per second of video) and compatible with Claude Desktop, Cursor, Windsurf, and any MCP stdio client.
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., "@Agnes AI MCP Server generate an image of a futuristic cityscape at night"
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.
ο»Ώ
π¨ Agnes AI MCP Server
Free Text-to-Image & Text-to-Video generation via Agnes AI
English | δΈζ
π Quick Start
# 1. Install (one command)
pip install agnes-mcp
# 2. Get a free API key at https://agnes-ai.com
# 3. Add to your MCP client config:Claude Desktop / Cursor / Windsurf (claude_desktop_config.json or equivalent):
{
"mcpServers": {
"agnes-mcp": {
"command": "uvx",
"args": ["agnes-mcp"],
"env": {
"AGNES_API_KEY": "your-api-key-here"
}
}
}
}Codex (config.toml):
[mcp_servers.agnes_mcp]
command = "uvx"
args = ["agnes-mcp"]
[mcp_servers.agnes_mcp.env]
AGNES_API_KEY = "your-api-key-here"That's it! Now you can generate images and videos directly from your AI assistant.
Related MCP server: Agnes Video MCP Server
β¨ Why Agnes MCP?
Feature | Agnes MCP | Other AI Image Services |
Price | $0 / image, $0 / second | $0.02 - $0.08 / image |
Text-to-Image | β 2 models (2.0 & 2.1 Flash) | β Usually 1 model |
Image-to-Image | β Reference image + prompt | β or limited |
Batch Generation | β 1-4 images at once | β |
Text-to-Video | β Up to 18s, 1080p | β or paid only |
Image-to-Video | β Static image β video | β or paid only |
Multi-image Video | β Keyframe animation | β |
Auto Download | β Saves locally automatically | β Manual download |
MCP Standard | β Full compliance | Varies |
Yes, it's completely free. Agnes AI currently offers all image and video generation at $0. Just register and get an API key.
πΌοΈ Demo
Text-to-Image (agnes-image-2.1-flash)
"A majestic dragon flying over a Chinese mountain landscape at sunset, cinematic lighting, epic fantasy art"

Text-to-Image (agnes-image-2.0-flash)
"A cozy Japanese ramen shop at night, warm lantern light, rain falling, anime style"

π¦ Tools
Tool | Description | Example |
| Generate image(s) from text |
|
| Generate from reference image(s) + text |
|
| Generate video from text/image(s) |
|
| Animate a static image into video |
|
| Smooth transition between keyframe images |
|
| Check async video task status |
|
βοΈ Environment Variables
Variable | Required | Default | Description |
| Yes | - | Your Agnes AI API key |
| No |
| API base URL |
| No |
| Default image model |
| No |
| Default image size |
π Get a Free API Key
Visit https://agnes-ai.com
Create an account (free)
Go to Console β API Keys β Create
Copy the key and paste into your config
β Supported Clients
Claude Desktop
Codex (OpenAI)
Cursor
Windsurf
Cherry Studio
Any MCP client with
stdiotransport
π Changelog
v0.3.0 (2026-06-28)
β¨ New tool:
image_to_videoβ animate a static image into videoβ¨ New tool:
keyframe_animationβ smooth transitions between multiple keyframe imagesβ¨
text_to_video: addedmodeandnum_inference_stepsparametersβ¨
create_video_task/generate_video: supportmode(e.g.ti2vid,keyframes) andnum_inference_stepsβ 28 tests passing
v0.2.0 (2026-06-27)
β¨ New tool:
image_to_imageβ generate from reference image(s) + promptβ¨
text_to_image: batch generation (n: 1-4) and multi-image composition (images)β¨
text_to_video: multi-image video / keyframe animation (images)π Unified multi-image download logic
β 19 tests passing
v0.1.1 (2026-06-26)
π Initial public release
text_to_image, text_to_video, check_video_status
Async httpx with retry mechanism
Auto-download to local filesystem
π€ Contributing
See CONTRIBUTING.md for guidelines.
π License
MIT
Available Tools
6 toolscheck_video_statusA
Check the status of a video generation task.
Args: video_id: The video_id returned from text_to_video. task_id: The task_id returned from text_to_video (alternative).
Returns: dict with task_id, video_id, status, progress, video_url, seconds, size, error.
Inputs: task_id, video_id. Returns: object
image_to_imageA
Generate new image(s) based on reference image(s) and a text prompt.
This is image-to-image generation: provide one or more reference images (as URLs) along with a text prompt describing the desired output.
Args: prompt: Text description guiding the generation. images: List of reference image URLs (at least one required). model: Model name (agnes-image-2.0-flash or agnes-image-2.1-flash). size: Output size (e.g. 1024x768, 1024x1024, 768x1024). n: Number of images to generate (1-4). Default: 1. output_dir: Directory to save the downloaded image(s). Defaults to ~/agnes_output. return_mode: 'url' for image URL, 'b64' for base64 + local save.
Returns: dict with url, local_path, model, size, n, images.
Inputs: images (required), prompt (required), n, size, +3 more. Returns: object
image_to_videoA
Animate a static image into a video using Agnes AI.
Provide a single image URL (or Data URI base64) and a text prompt describing the desired motion/animation.
This is an async operation that polls until completion (may take several minutes).
Args: prompt: Text description of the desired motion/animation. image: Input image URL or Data URI base64 (required). model: Model name. Default: agnes-video-v2.0 width: Video width. Default: 1152 height: Video height. Default: 768 num_frames: Total frames (8n+1 rule, max 441). Common values: 81(~3s), 121(~5s), 241(~10s), 441(~18s) frame_rate: FPS, 1-60. Default: 24 negative_prompt: Optional negative prompt to exclude from generation. seed: Optional random seed (-1 for random). num_inference_steps: Number of inference steps. Optional. output_dir: Directory to save the downloaded video. Defaults to ~/agnes_output.
Returns: dict with video_id, status, video_url, local_path, seconds, size.
Inputs: image (required), prompt (required), seed, model, +7 more. Returns: object
keyframe_animationA
Generate a smooth video transitioning between multiple keyframe images.
Provide 2+ image URLs as keyframes. The model generates a video that smoothly transitions between them, guided by the text prompt.
This is an async operation that polls until completion (may take several minutes).
Args: prompt: Text description guiding the animation and transitions. images: List of keyframe image URLs (at least 2 recommended). model: Model name. Default: agnes-video-v2.0 width: Video width. Default: 1152 height: Video height. Default: 768 num_frames: Total frames (8n+1 rule, max 441). Common values: 81(~3s), 121(~5s), 241(~10s), 441(~18s) frame_rate: FPS, 1-60. Default: 24 negative_prompt: Optional negative prompt to exclude from generation. seed: Optional random seed (-1 for random). num_inference_steps: Number of inference steps. Optional. output_dir: Directory to save the downloaded video. Defaults to ~/agnes_output.
Returns: dict with video_id, status, video_url, local_path, seconds, size.
Inputs: images (required), prompt (required), seed, model, +7 more. Returns: object
text_to_imageA
Generate images from text using Agnes AI.
Supports two models:
agnes-image-2.0-flash: Standard quality
agnes-image-2.1-flash: Enhanced quality (recommended)
Args: prompt: Text description of the image to generate. model: Model name (agnes-image-2.0-flash or agnes-image-2.1-flash). size: Output size (e.g. 1024x768, 1024x1024, 768x1024). n: Number of images to generate (1-4). Default: 1. images: Optional list of reference image URLs for multi-image composition. output_dir: Directory to save the downloaded image(s). Defaults to ~/agnes_output. return_mode: 'url' for image URL, 'b64' for base64 + local save.
Returns: dict with url, local_path, model, size, n, images.
Inputs: prompt (required), n, size, model, +3 more. Returns: object
text_to_videoA
Generate a video from text (and optional image(s)) using Agnes AI.
This is an async operation that polls until completion (may take several minutes).
Args: prompt: Text description of the video content. model: Model name. Default: agnes-video-v2.0 width: Video width. Default: 1152 height: Video height. Default: 768 num_frames: Total frames (8n+1 rule, max 441). Common values: 81(~3s), 121(~5s), 241(~10s), 441(~18s) frame_rate: FPS, 1-60. Default: 24 image: Optional single image URL for image-to-video. images: Optional list of image URLs for multi-image video / keyframe animation. When provided, 'image' is ignored. negative_prompt: Optional negative prompt to exclude from generation. seed: Optional random seed (-1 for random). mode: Generation mode (e.g. 'ti2vid', 'keyframes'). Optional. num_inference_steps: Number of inference steps. Optional. output_dir: Directory to save the downloaded video. Defaults to ~/agnes_output.
Returns: dict with video_id, status, video_url, local_path, seconds, size.
Inputs: prompt (required), mode, seed, image, +9 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
The primary tools are clearly separated by source and target modality (text/image/video), making their main purposes easy to distinguish. However, text_to_video also accepts optional image(s) and keyframe modes, which creates some boundary overlap with image_to_video and keyframe_animation.
Four tools follow a clean source_to_target naming pattern (text_to_image, image_to_image, text_to_video, image_to_video), and all names use snake_case. keyframe_animation and check_video_status break the pattern slightly, but the convention is still predictable and readable.
Six tools is a well-scoped size for a media generation server, covering both image and video generation without redundancy or bloat. Each tool provides a distinct high-level capability, and the count feels appropriate for the domain.
The set covers the core generation workflows: text-to-image, image-to-image, text-to-video, image-to-video, and keyframe animation, plus async status checking. Minor gaps exist, such as no model listing or task cancellation, but agents can complete all primary generation tasks without dead ends.
Maintenance
Related MCP Connectors
Generate images, videos and music with model discovery, cost estimates and asynchronous results.
Generate AI images, videos, music, SFX & speech in any AI assistant. Results appear inline in chat.
LLM chat, text tools, image generation, editing, batch image jobs, and asynchronous video generation
AI image + video generation for agents: --flag prompt DSL, async generate/poll, x402 pay-per-use.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables text-to-image generation using Agnes Image 2.1 Flash via OpenAI-compatible API, supporting aspect ratios, custom resolution, and multi-image generation.11MIT
- AlicenseAqualityDmaintenanceEnables video generation from text prompts or images using Agnes AI's video models, with async task submission and status polling.21MIT
- FlicenseAqualityCmaintenanceEnables AI assistants to generate images and videos via the Agnes AI API, supporting text-to-image, image-to-image, and video generation.31-
- AlicenseBqualityCmaintenanceEnables AI agents to generate and edit images and videos using the Agnes API (Chinese version). Supports standard and high-resolution image generation, image editing, video submission, and status polling.72MIT