PicMovi Photo to Video MCP

Open-source agent tools for PicMovi, a photo to video platform: turn still photos into short clips, or make video from photos with an optional last-frame still.

This repository ships a typed REST client, a CLI, and a local stdio MCP adapter. Live identity, credits, quotes, owned photos, plan concurrency, and video jobs are served by PicMovi Agent REST (/api/agent/v1/*). Hosted Streamable HTTP MCP (/api/mcp + OAuth) is the later remote-MCP path.

What agents can do

Connected agents can:

1. Discover photo-to-video models (models_list)

2. Check spendable credits (credits_get)

3. Quote a photo-to-video job (generation_quote) — no charge

4. After explicit credit approval, start one job (generation_create)

5. Poll the clip (generation_get)

Credits are spent only when a video is actually submitted, at the same list prices as picmovi.com. Listing models, quoting, and polling do not deduct credits.

Related MCP server: ShotFlow MCP Server

Hosted MCP (OAuth, later)

When the host supports remote MCP, the Streamable HTTP endpoint will be:

{
  "mcpServers": {
    "picmovi": {
      "url": "https://picmovi.com/api/mcp"
    }
  }
}

Until that ships, use the local stdio adapter below. It calls Agent REST on PICMOVI_BASE_URL (production https://api.picmovi.com). Keys and photo IDs come from picmovi.com/mcp.

Local stdio MCP

{
  "mcpServers": {
    "picmovi": {
      "command": "npx",
      "args": ["-y", "picmovi-mcp"],
      "env": {
        "PICMOVI_API_KEY": "${PICMOVI_API_KEY}",
        "PICMOVI_BASE_URL": "https://api.picmovi.com"
      }
    }
  }
}

From this repo while developing, args must be an absolute path to packages/mcp/dist/index.js (a relative path is resolved from the home directory and fails):

{
  "mcpServers": {
    "picmovi": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/picmovi_mcp/packages/mcp/dist/index.js"],
      "cwd": "/ABSOLUTE/PATH/picmovi_mcp",
      "env": {
        "PICMOVI_MOCK": "1"
      }
    }
  }
}

PICMOVI_MOCK=1 runs a local dry-run so you can wire Cursor without a live key. It still enforces photo-to-video quotes, idempotency, and a per-account parallel limit. It does not read your picmovi.com credits.

Create a key on picmovi.com/mcp. See docs/agent-api.md for the REST contract the adapter calls.

Prompt template

Same copy as picmovi.com/mcp. Paste into the agent after you click a photo on that page. “Use photo-to-video.…” picks the model (no picker in chat). Motion prompt is the same i2v text you type in the studio — what happens in the clip. “subtle motion” is motion strength, not that story. Delete the Motion prompt line if you only want a generic animate.

Animate my photo assetId: PASTE_ASSET_ID_HERE
for 5 seconds with subtle motion.
Use photo-to-video.seedance25 at 480p.
Motion prompt: She blinks slowly, a light breeze moves her hair, camera stays locked.
Quote credits first, then generate after I confirm.

CLI

npm run build
export PICMOVI_MOCK=1
node packages/cli/dist/index.js models list
node packages/cli/dist/index.js quote \
  --capability photo-to-video.seedance25 \
  --photo asset_start \
  --duration 5s \
  --resolution 480p

generate quotes first and requires --yes --confirm-credits=<exact quote> plus a stable --request-id when you retry.

Photo to video workflow

1. Discover. Call models_list. Pick a returned id such as photo-to-video.seedance25. Do not invent a model.

2. Prepare the photo. Upload through a trusted PicMovi surface. Pass assetIds.images[0] as the start photo. If the capability sets endImageSupported, images[1] is the optional last frame.

3. Quote. Call generation_quote with capabilityId, motion prompt, values (duration, resolution, camera), and assetIds. Treat quotedCredits as authoritative.

4. Confirm. Show the human the exact credit amount to make video from this photo. A vague “generate” is not confirmation.

5. Create once. Send the same payload, confirmedCredits, and a new stable clientRequestId. Reuse that id only for the identical request.

6. Poll. Call generation_get. Do not create again after a timeout or submission_unknown.

Concurrency

The same PicMovi account cannot stack unlimited parallel photo-to-video jobs. The server returns:

Read-only tools do not occupy concurrency slots.

Development

npm install
npm test
npm run build

Packages:

• @picmovi/agent-core — photo-to-video catalog, quotes, mock backend

• @picmovi/client — Agent REST v1 client

• picmovi-cli — command-line adapter

• picmovi-mcp — local stdio MCP adapter

• server.json — hosted MCP Registry metadata

Publishing this listing

Submit the public GitHub repo at https://mcpservers.org/submit. Details: docs/publishing.md. Contract: docs/tool-contract.md. Prompt template: docs/prompt-template.md. Agent skill: skills/picmovi-photo-to-video/SKILL.md.

Security and license

Do not commit API keys. Hosted MCP uses OAuth; local adapters read PICMOVI_API_KEY from the environment. MIT-0, see LICENSE.