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 24 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, and delete.
• AI Video: discover models, estimate cost, generate, get one or many, list, and delete.
• Images and speech: discover image models, generate or edit images, and synthesize MP3 audio.
• Assets and account: upload, list, and delete assets; list avatar models; check credits.

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 at visionstory.ai/openapi (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.

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