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_image
• Video Generation — Text-to-video and image-to-video via generate_video + get_video
• Two Transport Modes — stdio (local) and Streamable HTTP (remote)
• Auto Download — Optionally save generated media to disk automatically
• Blocking & Async — wait=true for synchronous generation, or poll with get_video

Quick Start

1. Install Dependencies

cd agnes-mcp-server
npm install
npm run build

2. 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.cjs

Streamable 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_image	Generate or edit an image. Supports text-to-image and image-to-image modes.
generate_video	Submit a video generation task. Set wait=true to block until complete.
get_video	Query video generation status and optionally download the result.

Tool Parameters

generate_image

Parameter	Type	Required	Default	Description
prompt	string	Yes	—	Text description of the desired image
size	string	No	1024x1024	Image dimensions (e.g., 512x512, 1024x1024)
images	string[]	No	—	Input images (local file paths or base64 data URIs)
format	"url" | "b64"	No	url	Output format when no outputDir is set
outputDir	string	No	—	Directory to download the image file

generate_video

Parameter	Type	Required	Default	Description
prompt	string	Yes	—	Text description of the desired video
image	string | string[]	No	—	Input image(s) for image-to-video mode
mode	string	No	—	Generation mode (e.g., "image-to-video")
width	number	No	—	Video width
height	number	No	—	Video height
num_frames	number	No	—	Number of frames
frame_rate	number	No	—	Frames per second
seed	number	No	—	Random seed for reproducibility
negative_prompt	string	No	—	Things to exclude from the video
outputDir	string	No	—	Directory to download the video file
wait	boolean	No	false	Block until generation completes

get_video

Parameter	Type	Required	Default	Description
videoId	string	Yes	—	Video ID returned by generate_video
taskId	string	No	—	Task ID (fallback for querying)
outputDir	string	No	—	Directory to download the video file

Environment Variables

Variable	Required	Default	Description
AGNES_API_KEY	Yes	—	Your Agnes API key (starts with sk-)
MCP_TRANSPORT	No	stdio	Transport mode: stdio or http
HTTP_PORT	No	3100	HTTP server port (only in http mode)
DEFAULT_DOWNLOAD_DIR	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.json

Development

# Watch mode (TypeScript → Node)
npm run dev

# Build TypeScript
npm run build

# Create standalone bundle
npm run bundle

# Run smoke test
npm run test

Test 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.ts

License

MIT