@neosamon/agnes-mcp-server

MCP server that exposes Agnes AI's image/video generation and image understanding to MCP clients (Claude Code, etc.). Fills the gaps where Claude cannot generate images/videos or read URL-based images.

Capabilities

• Image generation — text-to-image and image-to-image, up to 4K
• Image transform — local resize / crop / rounded corners / format (no AI); ideal for building app icons
• Video generation — text-to-video and image-to-video, up to 1080p ~7s or 480p ~40s
• Image understanding — describe/analyze a remote URL or local file image

Generated assets auto-download to local paths; tools return both local path and remote URL.

Install

Add to ~/.claude.json (user-level) or project .mcp.json:

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

Get an API key at agnes-ai.com.

Tools

| Tool | Purpose | Returns | |------|---------|---------| | submit_image_task | Async text-to-image / image-to-image | task_id | | check_image_status | Poll image task; auto-downloads on completion | local path + URL | | list_image_tasks | List local image tasks (filterable by status) | task list | | edit_image | Sync image-to-image transform (reference images + prompt) | local path + URL | | transform_image | Local pixel ops pipeline: resize / crop / rounded corners (simple or iOS-style squircle) / format | local path | | analyze_image | Image (URL or local path) + question → text answer | text | | submit_video_task | Async text-to-video / image-to-video | task_id + video_id | | check_video_status | Poll video task; auto-downloads on completion | local path + URL | | list_video_tasks | List local video tasks (filterable by status) | task list |

Generation is async: call submit_* once, then check_*_status until the task completes. edit_image, transform_image, and analyze_image are synchronous.

Video size and frame limits

Agnes caps num_frames per resolution tier; oversize combos are rejected client-side.

| Tier | Sizes | Max frames | Duration @ 24fps | |------|-------|-----------|------------------| | 1080p | 1920x1080, 1080x1920 | 169 | ~7s | | 720p | 1152x768, 768x1152, 1280x768, 1280x720, 720x1280 | 409 | ~17s | | 480p | 640x480, 480x640 | 961 | ~40s |

Pick by goal: highest resolution → 1080p + 169; longest duration → 480p + 961; balanced → 720p + 409.

Submit is auto-retried on timeout (4 attempts, exponential backoff). The Agnes backend intermittently hangs on submit, especially for 480p — retry absorbs most flakiness.

Image transform

transform_image runs a local pixel pipeline via sharp — no AI calls. Useful for preparing app icons:

[resize 1024×1024 cover] → [rounded_corners style=apple_squircle] → output.png

| Operation | Fields | |-----------|--------| | resize | width, height, fit (cover / contain / fill) | | crop | left, top, width, height | | rounded_corners | style (simple arc corners, or apple_squircle continuous-curvature bezier), radius_percent (0-50, simple only, default 22.5) | | format | format (png / jpeg / webp), quality (1-100, jpeg/webp only) |

For iOS-style icons, use style: "apple_squircle" with a prior resize to square. Put resize/crop before rounded_corners in the pipeline.

Environment variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | AGNES_API_KEY | yes | — | API key | | AGNES_API_BASE | no | https://apihub.agnes-ai.com | API base URL | | AGNES_OUTPUT_DIR | no | ~/.agnes-mcp/output | Output directory | | AGNES_DEFAULT_IMAGE_MODEL | no | agnes-image-2.1-flash | Default image model | | AGNES_DEFAULT_VIDEO_MODEL | no | agnes-video-v2.0 | Default video model | | AGNES_DEFAULT_CHAT_MODEL | no | agnes-2.0-flash | Default chat model (used by analyze_image) | | LOG_LEVEL | no | info | trace / debug / info / warn / error | | LOG_TO_FILE | no | false | Write logs to file | | LOG_FILE_PATH | no | /tmp/agnes-mcp.log | Log file path |

Output storage

<AGNES_OUTPUT_DIR>/
  images/   agnes-<id>.png   + .history.json
  videos/   agnes-<id>.mp4   + .tasks.json

Each generation tool takes an optional output_path:

• omitted → default dir + auto filename
• directory → that dir + auto filename
• full path → used as-is (parent created if needed)

Development

npm install
npm run build
npm test

See DEVELOPMENT.md and ARCHITECTURE.md.

License

MIT