@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:

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

Getting an API Key

1. Sign up at puppetry.com
2. Go to Settings → API Keys
3. 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