<div align="center">

🎨 Agnes AI MCP Server

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

English | 中文

</div>

---

🚀 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.

---

✨ 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
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

• [x] Claude Desktop
• [x] Codex (OpenAI)
• [x] Cursor
• [x] Windsurf
• [x] Cherry Studio
• [x] 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