Agnes Video MCP Server

Production-grade Model Context Protocol server for AI video generation — supporting Agnes, Runway, Pika, Luma, Kling, Veo, and Wan.

Overview

agnes-video-mcp is a production-grade MCP (Model Context Protocol) server that enables AI assistants (like Claude) to generate videos using multiple AI providers through a unified interface.

Key Features

• 8 Production Tools — text-to-video, image-to-video, multi-image, keyframes, status, wait, cancel, smart dispatcher
• Smart Dispatcher — Claude calls generate_video once; the server auto-detects mode and routes to the right provider
• Auto-Validation — frame counts auto-corrected to 8n+1 formula; durations auto-converted to frames
• Multi-Provider — Agnes (fully implemented), with stubs for Runway, Pika, Luma, Kling, Veo, Wan
• Resilient — automatic retry with exponential backoff, rate-limit handling, configurable timeouts
• Docker Ready — multi-stage build, slim Alpine image, tini init
• CI/CD — automated lint, typecheck, build, test, and npm publish on release

Quick Start

Prerequisites

• Node.js >= 20
• An Agnes API key

Install

npm install agnes-video-mcp

Configure

export AGNES_API_KEY=sk-UDICorllDOuf8Xmk3IB0gTx9yUDncf8IKcYAvqCnWvapTcZv

Run

# Direct
npx agnes-video-mcp

# Docker
docker run -e AGNES_API_KEY=sk-UDICorllDOuf8Xmk3IB0gTx9yUDncf8IKcYAvqCnWvapTcZv ghcr.io/xiooLoo/agnes-video-mcp:latest

Claude Desktop Config

{
  "mcpServers": {
    "agnes-video": {
      "command": "npx",
      "args": ["agnes-video-mcp"],
      "env": {
        "AGNES_API_KEY": "sk-UDICorllDOuf8Xmk3IB0gTx9yUDncf8IKcYAvqCnWvapTcZv"
      }
    }
  }
}

Available Tools

| Tool | Description | |------|-------------| | text_to_video | Generate video from text prompt | | image_to_video | Generate video from a single image | | multi_image_to_video | Generate video from 2-10 images (transition/sequence/collage) | | keyframes_video | Animated keyframe transitions | | video_status | Query task status | | wait_video | Poll until task completes | | cancel | Cancel a running task | | list_models | List available models | | generate_video | Smart dispatcher — auto-detects mode and provider |

Smart Dispatcher (generate_video)

The generate_video tool is the recommended entry point. It automatically:

1. Detects the mode — text-to-video, image-to-video, multi-image, or keyframes based on input
2. Selects the provider — defaults to Agnes, configurable via provider parameter
3. Validates and corrects — frame counts normalized to 8n+1, durations auto-calculated
4. Polls and waits — returns the final video URL directly

Claude: "Make a panda ride a bicycle"
MCP:    → text_to_video (auto-detected)
        → polls until complete
        → returns download URL

Claude: "Animate this image" + [image URL]
MCP:    → image_to_video (auto-detected)
        → polls until complete
        → returns download URL

Configuration

| Variable | Default | Description | |----------|---------|-------------| | AGNES_API_KEY | (required) | Agnes API key | | AGNES_BASE_URL | https://api.agnes.ai/v1 | Agnes API base URL | | RUNWAY_API_KEY | | Runway API key | | PIKA_API_KEY | | Pika API key | | LUMA_API_KEY | | Luma API key | | KLING_API_KEY | | Kling API key | | VEO_API_KEY | | Veo API key | | WAN_API_KEY | | Wan API key | | MAX_CONCURRENT_TASKS | 5 | Max concurrent video tasks | | POLL_INTERVAL_MS | 3000 | Polling interval in ms | | TASK_TIMEOUT_MINUTES | 30 | Task timeout | | RETRY_MAX_ATTEMPTS | 3 | Max retry attempts | | RETRY_BASE_DELAY_MS | 1000 | Base delay for exponential backoff | | DEFAULT_PROVIDER | agnes | Default provider | | LOG_LEVEL | info | Logging level: silent/info/debug/verbose |

Development

# Clone and install
git clone https://github.com/xiooLoo/agnes-video-mcp.git
cd agnes-video-mcp
npm install

# Development mode (auto-reload)
npm run dev

# Build
npm run build

# Lint & typecheck
npm run lint
npm run typecheck

# Test
npm test
npm run test:coverage

Project Structure

agnes-video-mcp/
├── src/
│   ├── api/              # AgnesClient, RetryClient
│   ├── tools/            # MCP tool implementations
│   ├── providers/        # Multi-provider abstraction
│   ├── types/            # TypeScript types & errors
│   ├── logger/           # Structured logger
│   ├── config/           # Environment config loader
│   ├── mcp/              # MCP server setup & tool registration
│   ├── index.ts          # Public exports
│   ├── server.ts         # Entry point
│   └── cli.ts            # CLI binary
├── tests/
│   ├── unit/             # Unit tests
│   └── integration/      # Integration tests
├── docs/                 # Extended documentation
├── examples/             # Usage examples
├── Dockerfile
├── .github/workflows/    # CI/CD pipelines
└── package.json

License

MIT