visionstory-mcp

MCP server for the VisionStory API — task-oriented tools that let AI agents (Claude Desktop, Cursor, and any Model Context Protocol client) generate AI talking-avatar videos without writing code.

It exposes all 28 public API operations, kept in sync with the visionstory SDK and visionstory CLI:

• Talking-avatar videos: generate, get, list, and delete.
• Avatars and voices: create or clone, list, update owned-avatar framing, and delete.
• AI Video: discover models, estimate cost, generate, get one or many, list, and delete.
• Images, speech, and audio: discover image models, generate or edit images, synthesize localized MP3 audio, transcribe speech, and align known text with word timestamps.
• Assets and account: upload, list, and delete assets; list avatar models; check credits.

On startup, the local server checks the shared release manifest and writes an upgrade notice to stderr when a newer package is available. Agents can read visionstory://release for the installed and latest versions, feature highlights, release notes, and the upgrade command. Set VISIONSTORY_UPDATE_CHECK=0 to disable the check.

Delete tools require confirm=true after explicit user confirmation. The local stdio server keeps direct local-file support for avatar, voice, talking-video, and asset workflows.

Install & run

Requires an API key — create one on the VisionStory API keys page (Pro plan and up) and set it as VISIONSTORY_API_KEY.

Add it to Claude Desktop (or any MCP client):

{
  "mcpServers": {
    "visionstory": {
      "command": "uvx",
      "args": ["visionstory-mcp"],
      "env": { "VISIONSTORY_API_KEY": "sk-vs-xxxxxxxxxxxxxxxxxxx" }
    }
  }
}

generate_video and generate_ai_video submit and poll to completion, returning the final video URL — one call in, one result out. create_speech returns standard MCP audio content plus usage metadata. transcribe_audio and align_audio accept a local WAV/MP3 file, public URL, or reusable asset ID.

The visionstory://contract MCP resource reports the same contract version, SHA-256 fingerprint, and operation count as visionstory.get_contract_info() and visionstory contract.

Run standalone

Verify that the package and all public tools load, then exit:

uvx visionstory-mcp --check

Run the stdio server for an MCP client:

export VISIONSTORY_API_KEY="sk-vs-xxxxxxxxxxxxxxxxxxx"
uvx visionstory-mcp          # or: python -m visionstory_mcp

The normal server command waits silently for MCP messages. Use --check when testing it directly in a terminal.

License

MIT

Structured media understanding

Use understand_media(prompt, inputs, schema) for structured extraction from 1–8 images, audio clips, or videos. The prompt must contain 1–5000 characters and the JSON Schema must describe a top-level object. The synchronous call allows 180 seconds and returns output, token usage, and cost_credit; there is no model selector or free-text mode. Successful calls are charged, so do not automatically repeat timeouts.

Remote MCP accepts media URLs or asset IDs; local MCP additionally accepts inline_data. The Agent Skill helper exposes understand-media --prompt ... --inputs ... --schema .... Both MCP variants also accept optional speech_rate (slow, normal, fast) on create_speech; omission or null uses normal speed.

See Media Understanding and Text to Speech for complete contracts.