Agnes MCP Server
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 MCP Server Generate an image of a futuristic city at sunset, 1920x1080"
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 MCP Server
An MCP (Model Context Protocol) server that wraps the Agnes AI image and video generation APIs, enabling AI assistants (Claude, Cursor, VS Code, etc.) to generate images and videos via standardized tool calls.
Features
Image Generation — Text-to-image and image-to-image via
generate_imageVideo Generation — Text-to-video and image-to-video via
generate_video+get_videoTwo Transport Modes —
stdio(local) andStreamable HTTP(remote)Auto Download — Optionally save generated media to disk automatically
Blocking & Async —
wait=truefor synchronous generation, or poll withget_video
Related MCP server: ImaginePro MCP Server
Quick Start
1. Install Dependencies
cd agnes-mcp-server
npm install
npm run build2. Set API Key
export AGNES_API_KEY="sk-agnes-your-api-key-here"3. Run the Server
Stdio mode (default, for local MCP clients like Claude Desktop, Cursor):
npm run start
# or
node agnes-mcp-server.cjsStreamable HTTP mode (for remote MCP clients):
MCP_TRANSPORT=http npm run start:http
# Default port: 3100 (configurable via HTTP_PORT)4. Configure Your MCP Client
Add this to your MCP client configuration (e.g., .mcp.json):
{
"mcpServers": {
"agnes": {
"command": "node",
"args": ["agnes-mcp-server.cjs"],
"env": {
"AGNES_API_KEY": "sk-agnes-your-api-key-here"
}
}
}
}Available Tools
Tool | Description |
| Generate or edit an image. Supports text-to-image and image-to-image modes. |
| Submit a video generation task. Set |
| Query video generation status and optionally download the result. |
Tool Parameters
generate_image
Parameter | Type | Required | Default | Description |
| string | Yes | — | Text description of the desired image |
| string | No |
| Image dimensions (e.g., |
| string[] | No | — | Input images (local file paths or base64 data URIs) |
|
| No |
| Output format when no |
| string | No | — | Directory to download the image file |
generate_video
Parameter | Type | Required | Default | Description |
| string | Yes | — | Text description of the desired video |
| string | string[] | No | — | Input image(s) for image-to-video mode |
| string | No | — | Generation mode (e.g., |
| number | No | — | Video width |
| number | No | — | Video height |
| number | No | — | Number of frames |
| number | No | — | Frames per second |
| number | No | — | Random seed for reproducibility |
| string | No | — | Things to exclude from the video |
| string | No | — | Directory to download the video file |
| boolean | No |
| Block until generation completes |
get_video
Parameter | Type | Required | Default | Description |
| string | Yes | — | Video ID returned by |
| string | No | — | Task ID (fallback for querying) |
| string | No | — | Directory to download the video file |
Environment Variables
Variable | Required | Default | Description |
| Yes | — | Your Agnes API key (starts with |
| No |
| Transport mode: |
| No |
| HTTP server port (only in |
| No | — | Root directory for auto-downloaded media |
Project Structure
agnes-mcp-server/
├── src/
│ ├── app/ # Server entry points (stdio, http, bundle)
│ ├── client/ # HTTP client wrapper
│ ├── core/ # Core MCP setup and registry
│ ├── module/
│ │ ├── image/ # Image generation service
│ │ └── video/ # Video generation service
│ ├── providers/ # API providers (AgnesClient, image, video)
│ ├── tools/ # MCP tool implementations
│ └── types/ # Shared types and result formatters
├── agnes-mcp-server.cjs # Bundled entry point
├── agnes-bundle.cjs # Standalone bundle
├── SKILL.md # MCP skill definition
├── TOKEN_AUTH.md # Authentication documentation
└── package.jsonDevelopment
# Watch mode (TypeScript → Node)
npm run dev
# Build TypeScript
npm run build
# Create standalone bundle
npm run bundle
# Run smoke test
npm run testTest Script
A standalone test script is included for verifying the image-to-video API flow:
npx tsx test-video-image.ts <local-image-path> <api-key>
# or
IMAGE_PATH=test.jpg AGNES_API_KEY=sk-xxx npx tsx test-video-image.tsLicense
MIT
Available Tools
3 toolsgenerate_imageB
Generate or edit an image using the Agnes AI image generation API. Supports text-to-image and image-to-image modes.
Inputs: prompt (required), size, format, images, +1 more.
generate_videoA
Submit a video generation task. By default returns a videoId immediately for progress polling with get_video. Set wait=true to block until generation completes. Optionally provide outputDir to auto-download the video when completed.
Inputs: prompt (required), mode, seed, wait, +7 more.
get_videoA
Get the current status of a video generation task and optionally download it. Accepts videoId (required) and taskId (optional). Returns progress percentage, status (queued/in_progress/completed/failed), and download URL when completed. Provide outputDir to auto-download the video file when generation is complete.
Inputs: videoId (required), taskId, outputDir.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool targets a distinct operation: image generation, video generation submission, and video status polling/download. No overlapping functionality, making selection unambiguous.
All tool names follow a consistent verb_noun pattern in snake_case (generate_image, generate_video, get_video), with no deviations or mixed conventions.
Three tools cover the essential workflows for image and video generation without unnecessary bloat, fitting well within the ideal 3-15 range.
Core generation and status retrieval are covered. Missing delete or list operations for generated content, but these are minor gaps given the server's likely purpose.
Maintenance
Related MCP Connectors
Generate AI images, videos, music, SFX & speech in any AI assistant. Results appear inline in chat.
Image and video AI tools and your own pipelines, run from any AI assistant.
Generate and edit images, video, voice, lip-sync and 3D models from your AI agent.
Make AI images, video, voiceovers and music, and edit video, from your assistant. Paid in credits.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI assistants to generate images, text, and audio content through the Pollinations APIs. Provides direct access to multimodal generation capabilities including image creation from text prompts, text-to-speech, and text generation.12154 npmMIT
- AlicenseBqualityDmaintenanceEnables AI assistants to generate images and videos through natural language using ImaginePro's API. Supports text-to-image generation, video creation, image upscaling, variants, inpainting, and multi-modal generation with real-time progress tracking.812 npmMIT
- AlicenseAqualityCmaintenanceEnables text-to-image and text-to-video generation via the Agnes AI API, with support for multiple models, async video generation, and automatic file downloads.61MIT
- AlicenseBqualityDmaintenanceEnables generating images from text or transforming existing images using GPT-Image-compatible APIs, with support for OpenAI and Agnes AI backends.2MIT