Skip to main content
Glama

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

Related MCP server: ImaginePro MCP Server

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

Available Tools

3 tools
generate_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

    A3.8/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool targets a distinct operation: image generation, video generation submission, and video status polling/download. No overlapping functionality, making selection unambiguous.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (generate_image, generate_video, get_video), with no deviations or mixed conventions.

    Tool Count5/5

    Three tools cover the essential workflows for image and video generation without unnecessary bloat, fitting well within the ideal 3-15 range.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers