@puppetry.com/mcp-server

@puppetry.com/mcp-server

MCP server for Puppetry — turn any portrait photo into a realistic talking AI video.

500+ voices · 29 languages · Lip-synced animation

Quick Start

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "puppetry": {
      "command": "npx",
      "args": ["-y", "@puppetry.com/mcp-server"],
      "env": {
        "PUPPETRY_API_KEY": "pk_live_your_api_key_here"
      }
    }
  }
}

OpenAI Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.puppetry]
command = "npx"
args = ["-y", "@puppetry.com/mcp-server"]
env = { PUPPETRY_API_KEY = "pk_live_your_api_key_here" }

Cursor

Add the same JSON block as Claude Desktop to .cursor/mcp.json.

HTTP Transport

PUPPETRY_API_KEY=pk_live_... npx @puppetry.com/mcp-server --http
# Server starts on http://localhost:3100/mcp

Hosted HTTP deployments expose unauthenticated probes for load balancers and agent setup checks:

• GET /health returns status/version metadata.
• GET / returns the MCP endpoint, auth scheme, docs URL, and advertised tools.
• CORS headers are sent on probes, auth errors, preflight, and /mcp responses so browser-hosted agent clients can read Mcp-Session-Id and MCP-Protocol-Version.
• Missing or invalid API keys return a standard WWW-Authenticate: Bearer challenge for hosted MCP clients that auto-discover bearer auth.

Tools

The package exposes the SDK-compatible Puppetry agent tool names used by Claude Desktop, Cursor, and other MCP clients:

Tool	Description
puppetry_create_video_from_text	Create a talking-head video from text + portrait
puppetry_create_video_from_audio	Create a talking-head video from audio + portrait
puppetry_create_audio_upload_url	Reserve a hosted signed audio upload URL
puppetry_lipsync	Lip-sync a portrait with existing audio
puppetry_list_voices	Browse Puppetry voices
puppetry_get_job_status	Check generation status
puppetry_get_quota	Check video credits and monthly API usage

The SDK-compatible create tools forward optional lipSyncOnly, speed, webhookUrl, outputFormat, expressiveness, and seamlessLoop fields to the Puppetry API when the client provides them.

Video submit and status responses keep Puppetry API fields such as task_id, status_url, created_at, completed_at, retry_after_seconds, and idempotent_replay, and also include SDK-style aliases such as id, jobId, taskId, statusUrl, createdAt, completedAt, retryAfter, and idempotentReplay. That lets agents detect idempotent retry replays, preserve job lifecycle timestamps, and keep polling backoff without custom casing logic. Video submit and hosted audio upload tools accept either idempotencyKey or idempotency_key and send the value as the Developer API Idempotency-Key header. puppetry_create_video_from_text accepts text, script, or prompt for the spoken script and voice_id, voiceId, or voice for voice selection. It rejects conflicting values before creating a credit-backed job. Video tools accept image_url, imageUrl, image, portrait, portrait_url, portraitUrl, avatar, avatarUrl, avatar_url, photo, photoUrl, or photo_url for the hosted portrait image and reject conflicting values before calling the API. puppetry_get_job_status accepts jobId, job_id, taskId, task_id, or id, so agents can pass back whichever ID alias they kept from the submit response. Developer API failures are returned as MCP tool errors with a JSON body that includes error.status, error.code, error.details, error.retry_after_seconds, error.retryAfterSeconds, and error.retryAfter when the API provides them. Agents should use those fields to back off on rate limits, surface quota/auth failures, and avoid blind retry loops. Conflicting tool input aliases, such as passing different image_url and image values, return the same isError JSON shape with error.status=400 and error.code=invalid_tool_input.

For generated or local audio, call puppetry_create_audio_upload_url, PUT the audio bytes to the returned uploadUrl with the returned headers, then pass the returned readUrl into puppetry_create_video_from_audio. The upload tool accepts mime_type, mimeType, or contentType for the audio MIME type and content_length, contentLength, sizeBytes, file_size, or fileSize for the byte count.

Legacy aliases remain available for older configs:

Tool	Description
list_voices	Browse 500+ AI voices. Filter by language or gender.
create_puppet	Text-to-video: portrait photo + script + voice → talking video
animate_audio	Audio-to-video: portrait photo + audio file → lip-synced video
get_video_status	Check video generation progress and get download URL

The legacy create_puppet, animate_audio, and get_video_status names also accept SDK-style input aliases, including portrait URL aliases, script/text aliases, audioUrl/audio, idempotency-key aliases, and jobId/id polling aliases.

Example Usage

"Make this photo talk and say 'Hello world' in a British accent"

The AI assistant will:

• Call list_voices to find a British English voice
• Call create_puppet with your image URL, script, and voice ID
• Call get_video_status to poll until the video is ready
• Return the download URL

Getting an API Key

• Sign up at puppetry.com
• Go to Settings → API Keys
• Create a new Developer API key (starts with pk_live_)

API keys use Puppetry video credits. Use puppetry_get_quota to check the current credit balance, UTC-month video credit usage, refunds, and current-key usage before starting longer render jobs. The response keeps the raw video_credits API object and also includes videoCredits, creditsRemaining, creditsUsed, creditsTotal, periodStart, and periodEnd aliases for agent clients that prefer SDK-style fields.

Environment Variables

Variable	Required	Description
PUPPETRY_API_KEY	Yes	Your Puppetry API key (pk_live_...)
PUPPETRY_API_BASE	No	API base URL (default: https://www.puppetry.com)
PUPPETRY_AUTH_TIMEOUT_MS	No	API-key validation timeout (default: 10000)
PUPPETRY_API_TIMEOUT_MS	No	Puppetry API tool-call timeout (default: 300000)
MCP_ALLOWED_ORIGIN	No	Comma-separated CORS origins (default: *)
PORT	No	HTTP transport port (default: 3100)

Development

npm install
npm run build
npm start          # stdio transport
npm start -- --http  # HTTP transport
npm test

Live Smoke

Run the agent contract against a live Puppetry API key without submitting a render:

PUPPETRY_API_KEY=pk_live_... npm run smoke:live

The default smoke checks required MCP tool registration, required input schemas for the credit-backed agent tools, puppetry_get_quota, puppetry_list_voices, structured conflict errors for alias inputs, and a read-only missing-job status lookup that verifies structured isError JSON for agent-facing API failures. Deeper checks are opt-in so local runs do not spend credits or create upload reservations by accident:

PUPPETRY_API_KEY=pk_live_... \
PUPPETRY_MCP_SMOKE_CREATE_UPLOAD=1 \
npm run smoke:live

PUPPETRY_API_KEY=pk_live_... \
PUPPETRY_MCP_SMOKE_SUBMIT_VIDEO=1 \
PUPPETRY_MCP_SMOKE_IMAGE_URL=https://assets.example.com/portrait.jpg \
npm run smoke:live

License

MIT