Agnes MCP Server

MCP server for Agnes Image 2.1 Flash (text-to-image) and Agnes Video V2.0 (text-to-video, image-to-video, multi-image, keyframe animation), connected via OpenAI-compatible API.

Features

Image

• Generate images from text prompts
• Supports aspect ratios (1:1, 16:9, 9:16, 4:3, 3:4, etc.)
• Custom resolution (1K~4K)
• Multi-image generation
• Returns clickable image URLs

Video

• Text-to-Video: generate videos from a text prompt
• Image-to-Video: animate a static image
• Multi-Image Video: guide generation with multiple reference images
• Keyframe Animation: smooth transitions between keyframes
• Asynchronous task-based API (create task → poll for result)
• Configurable resolution, frame count, frame rate, seed, negative prompt
• Returns the final video URL when the task completes

Requirements

• Node.js >= 18
• A platform.agnes-ai.com API key

Install

cd agnes-mcp-server
npm install
npm start

Environment Variables

| Variable | Required | Default | Description | |---|---|---|---| | AGNES_API_KEY | ✅ | — | Your Agnes AI API key | | AGNES_IMAGE_MODEL | | agnes-image-2.1-flash | Image model name | | AGNES_VIDEO_MODEL | | agnes-video-v2.0 | Video model name | | AGNES_BASE_URL | | https://apihub.agnes-ai.com/v1 | API base URL |

CC-Switch / Claude Code Config

{
  "mcpServers": {
    "agnes": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@kk17/agnes-mcp-server"],
      "env": {
        "AGNES_API_KEY": "your-agnes-api-key"
      }
    }
  }
}

Tool: agnes_image_generate

| Parameter | Type | Required | Description | |---|---|---|---| | prompt | string | ✅ | Text description (Chinese/English) | | size | string | | Resolution (1024x1024, 1024x768, 768x1024) | | ratio | string | | Aspect ratio (1:1, 16:9, 9:16, 4:3, 3:4, etc.) | | n | number | | Number of images (default 1) |

Tool: agnes_video_generate

Creates an asynchronous video generation task. Returns video_id and task_id — use agnes_video_get_task to retrieve the final video URL.

| Parameter | Type | Required | Description | |---|---|---|---| | prompt | string | ✅ | Text description. Recommended: [Subject] + [Action] + [Scene] + [Camera] + [Lighting] + [Style] | | image | string | | Single image URL for image-to-video | | images | string[] | | Image URL array for multi-image video or keyframe animation | | mode | string | | ti2vid or keyframes | | width | integer | | Video width (default 1152; standardized to 480p/720p/1080p) | | height | integer | | Video height (default 768; standardized to 480p/720p/1080p) | | num_frames | integer | | Frame count, ≤ 441, must follow 8n+1 (e.g. 81, 121, 161, 241, 441) | | frame_rate | integer | | FPS, 1–60 (default 24). seconds = num_frames / frame_rate | | num_inference_steps | integer | | Inference steps | | seed | integer | | Random seed for reproducibility | | negative_prompt | string | | Content to avoid |

Common durations

| Duration | num_frames | frame_rate | |---|---|---| | ~3s | 81 | 24 | | ~5s | 121 | 24 | | ~10s | 241 | 24 | | ~18s | 441 | 24 |

Tool: agnes_video_get_task

Retrieves the status and result of a video task. When status is completed, the response includes the final video URL in remixed_from_video_id.

| Parameter | Type | Required | Description | |---|---|---|---| | video_id | string | ✅* | Video ID from the create-task response (recommended) | | task_id | string | ✅* | Task ID for the legacy retrieval endpoint | | use_legacy | boolean | | Use the legacy /v1/videos/{task_id} endpoint (default false) | | model_name | string | | Explicit model name when retrieving by video_id |

* Provide video_id (recommended) or task_id.

Task statuses

| Status | Description | |---|---| | queued | Waiting in queue | | in_progress | Generating | | completed | Done — video URL available | | failed | Generation failed |

License

MIT