@lavendly/mcp

Model Context Protocol server for Lavendly. Drop it into Claude Desktop, Cursor, Claude Code, or any MCP client and your agent gets 32 tools for building AI video: create, estimate cost, generate, edit, review, render, and publish.

Hosted or local

Hosted (no install). Lavendly runs the same tools at https://mcp.lavendly.ai/mcp (Streamable HTTP). Sign in with OAuth when your client asks, or send an API key as a Bearer header:

claude mcp add --transport http lavendly https://mcp.lavendly.ai/mcp

Local (this package). A stdio server that calls the public API at https://lavendly.ai/api with your API key.

npx -y @lavendly/mcp

Configure your client

Create a key in the app under Settings > API. Keys look like lv_....

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "lavendly": {
      "command": "npx",
      "args": ["-y", "@lavendly/mcp"],
      "env": { "LAVENDLY_API_KEY": "lv_..." }
    }
  }
}

Cursor

~/.cursor/mcp.json:

{
  "mcpServers": {
    "lavendly": {
      "command": "npx",
      "args": ["-y", "@lavendly/mcp"],
      "env": { "LAVENDLY_API_KEY": "lv_..." }
    }
  }
}

Claude Code

claude mcp add lavendly --env LAVENDLY_API_KEY=lv_... -- npx -y @lavendly/mcp

Environment variables

| Variable | Required | Purpose | | ---------------------- | ---------- | ---------------------------------------------------------------------------------------------- | | LAVENDLY_API_KEY | one of two | API key from Settings > API (recommended) | | LAVENDLY_USER_ID | one of two | Self-hosted identity header (local development only) | | LAVENDLY_API_BASE | no | Default https://lavendly.ai/api. Point it at a self-hosted API if you run one. | | LAVENDLY_TOOL_PREFIX | no | Prefix every tool name (e.g. lavendly_) to avoid collisions when loading several MCP servers |

The loop

1. create_workflow with shots, then estimate_cost. Tell the user the price and wait for approval.
2. generate_scene, then poll get_generation_status.
3. quality_check each scene; regenerate failures with the reroll_hint.
4. create_render (free once scenes are generated), then get_render for result.video_url.
5. list_channels, confirm with the user, then publish_video or schedule_video.

Verify

printf '%s\n%s\n%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | LAVENDLY_API_KEY=lv_dummy npx -y @lavendly/mcp

You'll see a serverInfo line and the 32-tool catalog.

Maintainers

src/catalog.mjs is generated from shared/mcpCatalog.mjs in the Lavendly repo. Edit the shared file, then run node scripts/sync-mcp-catalog.mjs. npm publish refuses to run while the copy is stale.

Docs

Full docs at https://docs.lavendly.ai/mcp/overview.

Skills (operating manuals for the agent) at https://docs.lavendly.ai/agent-skills/overview.

License

MIT