@agentmedia/mcp-server

@agentmedia/mcp-server

MCP server for agent-media — generate AI UGC videos from Claude Code, Cursor, Windsurf, or any MCP-compatible client.

UGC for developers. Script in, video URL out — directly from your IDE.

What It Does

Five tools that let AI agents generate UGC videos:

Tool	Description
create_video	Generate a UGC video from a script. Polls until complete, returns the video URL.
show_your_app	Generate an actor holding a phone that shows your app screenshot.
product_acting_ugc	Generate an actor presenting or reacting to a product image.
list_actors	Browse available AI actors — slugs, names, demographics.
get_video_status	Check a generation job's status, video URL, or error message.

Setup

1. Get an API Key

Sign up at agent-media.ai and generate an API key in Settings.

2. Configure Your IDE

Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "agent-media": {
      "command": "npx",
      "args": ["-y", "@agentmedia/mcp-server"],
      "env": {
        "AGENT_MEDIA_API_KEY": "ma_your_key_here"
      }
    }
  }
}

Cursor

Open Settings > MCP Servers > Add Server:

{
  "agent-media": {
    "command": "npx",
    "args": ["-y", "@agentmedia/mcp-server"],
    "env": {
      "AGENT_MEDIA_API_KEY": "ma_your_key_here"
    }
  }
}

Windsurf

Open Settings > MCP > Add:

{
  "agent-media": {
    "command": "npx",
    "args": ["-y", "@agentmedia/mcp-server"],
    "env": {
      "AGENT_MEDIA_API_KEY": "ma_your_key_here"
    }
  }
}

Global Install (Alternative)

npm install -g @agentmedia/mcp-server
export AGENT_MEDIA_API_KEY=ma_your_key_here
agent-media-mcp

Usage Examples

Once configured, ask your AI assistant:

"Generate a 10-second UGC video with Sofia explaining why our product is great"

"List available actors and create a SaaS Review video with an enthusiastic tone"

"Create a product acting UGC video with Sofia holding this perfume bottle image"

"Check the status of job abc123"

The MCP server handles the API calls, polling, and returns the finished video URL.

Tool Parameters

create_video

Parameter	Type	Description
script	string	Video script (50-3000 chars). Required unless prompt is set.
prompt	string	AI generates the script from this prompt.
actor_slug	string	Actor to use (from list_actors).
tone	string	energetic, calm, confident, dramatic
music	string	chill, energetic, corporate, dramatic, upbeat
style	string	Subtitle style — 17 options including hormozi, bold, neon, fire
target_duration	number	5, 10, or 15 seconds
aspect_ratio	string	9:16, 16:9, 1:1
allow_broll	boolean	Include AI-generated B-roll footage
template	string	saas-review, testimonial, monologue, listicle, etc.
composition_mode	string	pip for picture-in-picture
webhook_url	string	Async completion callback URL

product_acting_ugc

Parameter	Type	Description
product_image_url	string	Public product image URL. Required.
actor_slug	string	Actor to use (from list_actors). Required.
product_description	string	Product context used when script is omitted.
script	string	Exact words the actor says. Optional if product_description is provided.
template	string	product-in-hand, mirror-selfie, bathroom-reaction, kitchen-counter, car-selfie, couch-review, expert-interview, product-closeup
acting_style	string	raw-selfie, shocked, angry, excited, dramatic, weird-hook, casual-demo, honest-review
duration	number	5, 10, or 15 seconds
subtitle_style	string	hormozi or none

list_actors

Parameter	Type	Default	Description
limit	number	20	Max actors to return (max 200)
offset	number	0	Pagination offset

get_video_status

Parameter	Type	Required	Description
job_id	string	Yes	Job ID from create_video

Webhooks

Pass webhook_url to create_video to get notified when the job completes or fails instead of polling.

Payload on success: { job_id, status: "completed", video_url } Payload on failure: { job_id, status: "failed", error_message }

Must be https://, publicly reachable, max 2048 chars. On non-2xx response, agent-media retries 3× with exponential backoff (1 s, 4 s, 16 s). Query strings are preserved — append ?secret=MY_TOKEN to verify authenticity.

Environment Variables

Variable	Required	Default	Description
AGENT_MEDIA_API_KEY	Yes	—	Your API key (ma_xxx format)
AGENT_MEDIA_API_URL	No	Production API	Override the API base URL

Related Packages

Package	Description
@agentmedia/sdk	TypeScript SDK for direct API integration
agent-media-cli	CLI tool — generate videos from your terminal
@agentmedia/schema	Shared schema — enums, types, Zod validation
agent-media	Python SDK

Links

• Interactive API Docs
• OpenAPI Spec
• Website
• GitHub

License

Apache-2.0