🚀 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
- 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
Metadata
Release files for agnes-mcp 0.3.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agnes_mcp-0.3.1-py3-none-any.whl | Python 3 | none | any | Details for agnes_mcp-0.3.1-py3-none-any.whl |
Release files / agnes_mcp-0.3.1-py3-none-any.whl
| Download URL | agnes_mcp-0.3.1-py3-none-any.whl |
|---|---|
| Size | 9.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e973c83771111ba8c8ab4d931ace15995dfa6101e0d2e7a653a3ad2c1412af77
|
|
BLAKE2b-256 checksum How to use checksums |
c3db24a57ac7aedc8f3acefe6c2f83b7709d5361afee3ac630c49e3ed9f1ecac
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.3
|
Security for agnes-mcp 0.3.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.