1.0.4 • Published 6 months ago

@pictory/pictory-mcp-server v1.0.4

Weekly downloads
-
License
SEE LICENSE IN LI...
Repository
-
Last release
6 months ago

Pictory MCP Server (Node.js TypeScript)

A Model Context Protocol (MCP) server implementation in Node.js TypeScript for the Pictory AI video creation platform.

Features

This MCP server provides tools to interact with the Pictory API:

  • create-storyboard: Create a storyboard from a script
  • poll-storyboard-job-status: Monitor storyboard creation progress
  • get-storyboard-preview: Get preview URL for completed storyboards
  • render-video: Start video rendering from a storyboard
  • poll-video-job-status: Monitor video rendering progress
  • get-rendered-video-url: Get the final video URL
  • get-all-video-templates: Get all available video templates
  • get-video-template-detail: Get details of a specific video template
  • create-storyboard-from-template: Create a storyboard using a template

Prerequisites

  • Node.js 20+
  • Pictory API credentials

Installation

Install the package globally or use with npx:

npm install -g @pictory/pictory-mcp-server

Or use directly with npx:

npx @pictory/pictory-mcp-server

Usage

With MCP clients

Configure your MCP client to use this server. Example for Claude Desktop:

{
  "mcpServers": {
    "pictory": {
      "command": "npx",
      "args": ["-y", "@pictory/pictory-mcp-server"],
      "env": {
        "PICTORY_API_BASE_URL": "https://api.pictory.ai/pictoryapis/v1",
        "PICTORY_CLIENT_ID": "your_client_id",
        "PICTORY_CLIENT_SECRET": "your_client_secret",
        "PICTORY_USER_ID": "your_user_id"
      }
    }
  }
}

API Tools

create-storyboard

Creates a storyboard from a script.

Parameters:

  • script (required): Array of strings containing the voice-over text for each scene
  • title (optional): Video title (defaults to first 100 characters of first scene)
  • voice (optional): Voice to use (default: "Amanda")
  • width (optional): Video width in pixels (default: 1920)
  • height (optional): Video height in pixels (default: 1080)

Returns: Job ID for the storyboard creation

poll-storyboard-job-status

Polls the status of a storyboard job until completion.

Parameters:

  • jobId (required): The job ID from create-storyboard

Returns: Job completion status and preview availability

get-storyboard-preview

Gets the preview URL from a completed storyboard job.

Parameters:

  • jobId (required): The job ID from create-storyboard

Returns: Preview URL if available

render-video

Starts video rendering from a completed storyboard.

Parameters:

  • storyboardJobId (required): The job ID from a completed storyboard

Returns: Job ID for the video rendering

poll-video-job-status

Polls the status of a video rendering job until completion.

Parameters:

  • jobId (required): The job ID from render-video

Returns: Job completion status and video URL availability

get-rendered-video-url

Gets the video URL from a completed video rendering job.

Parameters:

  • jobId (required): The job ID from render-video

Returns: Final video URL if available

get-all-video-templates

Gets all available video templates from Pictory.

Parameters: None

Returns: List of all video templates with their IDs, names, and descriptions

get-video-template-detail

Gets detailed information about a specific video template.

Parameters:

  • templateId (required): The ID of the video template

Returns: Detailed template information including variables and structure

create-storyboard-from-template

Creates a storyboard using an existing video template.

Parameters:

  • templateId (required): The ID of the video template to use
  • templateVariables (required): Object containing template variables to replace

Returns: Job ID for the storyboard creation

Example Workflow

  1. Create a storyboard:
// Tool: create-storyboard
{
  "script": [
    "Welcome to our amazing product demo.",
    "Here are the key features that make us special.",
    "Thank you for watching!"
  ],
  "title": "Product Demo Video",
  "voice": "Amanda"
}
  1. Wait for storyboard completion and get preview:
// Tool: poll-storyboard-job-status
{ "jobId": "storyboard-job-123" }

// Tool: get-storyboard-preview
{ "jobId": "storyboard-job-123" }
  1. Render the final video:
// Tool: render-video
{ "storyboardJobId": "storyboard-job-123" }
  1. Wait for video completion and get URL:
// Tool: poll-video-job-status
{ "jobId": "video-job-456" }

// Tool: get-rendered-video-url
{ "jobId": "video-job-456" }

Error Handling

The server includes comprehensive error handling for:

  • Missing environment variables
  • API authentication failures
  • Network connectivity issues
  • Job timeout scenarios
  • Malformed requests

Example Claude Interactions

Once configured with Claude Desktop, you can interact with the Pictory MCP server naturally. Here are some examples:

Creating a Video from Script

You: Create a video with three scenes: "Welcome to AI video creation", "Pictory makes it simple", and "Start creating today"

Claude: I'll create a video for you using Pictory. Let me start by creating a storyboard with your script.

[Claude uses create-storyboard tool]

The storyboard creation has started (Job ID: sb_12345). Let me check the progress...

[Claude uses poll-storyboard-job-status tool]

Great! The storyboard is complete. Let me get the preview for you...

[Claude uses get-storyboard-preview tool]

You can preview your storyboard here: [preview URL]

Now I'll render the final video...

[Claude uses render-video tool]

Video rendering has started (Job ID: vid_67890). This may take a few minutes...

[Claude uses poll-video-job-status tool]

Perfect! Your video is ready. You can watch it here: [video URL]

Using Templates

You: Show me available video templates and create a video using one of them

Claude: Let me browse the available video templates for you.

[Claude uses get-all-video-templates tool]

I found several templates available. Let me get details about a popular one...

[Claude uses get-video-template-detail tool]

This template requires variables like "company_name" and "product_name". Let me create a video using this template with your information.

[Claude uses create-storyboard-from-template tool]

Template-based storyboard creation started! Let me monitor the progress and get your final video...

[Claude polls status and gets final video URL]

Development

For development information, see README-dev.md.

License

All Rights Reserved

mcppictoryvideoai
@modelcontextprotocol/sdkzod
1.0.4

6 months ago

1.0.3

6 months ago