Skip to main content
Glama
Agnes AI MCP Server
by MSWEIMZ

ο»Ώ

🎨 Agnes AI MCP Server

Free Text-to-Image & Text-to-Video generation via Agnes AI

PyPI version PyPI downloads CI License: MIT Python 3.10+ MCP Compatible

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"

Dragon over mountains

Text-to-Image (agnes-image-2.0-flash)

"A cozy Japanese ramen shop at night, warm lantern light, rain falling, anime style"

Ramen shop at night


πŸ“¦ Tools

Tool

Description

Example

text_to_image

Generate image(s) from text

prompt: "a cat" + optional n: 4, images: [ref_url]

image_to_image

Generate from reference image(s) + text

prompt: "make it cyberpunk" + images: [url]

text_to_video

Generate video from text/image(s)

prompt: "a cat dancing" + optional mode, num_inference_steps

image_to_video

Animate a static image into video

prompt: "zoom in slowly" + image: "url"

keyframe_animation

Smooth transition between keyframe images

prompt: "morph scene" + images: [url1, url2, ...]

check_video_status

Check async video task status

video_id: "xxx" or task_id: "xxx"


βš™οΈ Environment Variables

Variable

Required

Default

Description

AGNES_API_KEY

Yes

-

Your Agnes AI API key

AGNES_API_BASE

No

https://apihub.agnes-ai.com/v1

API base URL

AGNES_DEFAULT_MODEL

No

agnes-image-2.1-flash

Default image model

AGNES_DEFAULT_SIZE

No

1024x768

Default image size


πŸ”‘ Get a Free API Key

  1. Visit https://agnes-ai.com

  2. Create an account (free)

  3. Go to Console β†’ API Keys β†’ Create

  4. Copy the key and paste into your config


βœ… Supported Clients

  • Claude Desktop

  • Codex (OpenAI)

  • Cursor

  • Windsurf

  • Cherry Studio

  • Any MCP client with stdio transport


πŸ“‹ 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: added mode and num_inference_steps parameters

  • ✨ create_video_task / generate_video: support mode (e.g. ti2vid, keyframes) and num_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 tools
check_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

    A4.3/5.0

    Scored across 6 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers