@pictory/pictory-mcp-server/README.md

MCP server for Pictory AI video creation platform - now available as a Desktop Extension

# Pictory MCP Server - Desktop Extension

A Model Context Protocol (MCP) server implementation for the Pictory AI video creation platform, now available as a **Desktop Extension (.dxt)** for one-click installation in Claude Desktop and other compatible applications.

## 🚀 Installation Options

Choose your preferred installation method:

### Option 1: Desktop Extension (Recommended)

> ⚠️ **Important**: Make sure you have the latest version of Claude Desktop installed. Desktop Extensions require Claude Desktop v0.10.0 or higher. [Download the latest version here](https://claude.ai/download).

1. **Download** the latest `.dxt` file: [pictory-mcp-server.dxt](https://mcp.pictorycontent.com/latest/pictory-mcp-server.dxt)
2. **Double-click** the downloaded `.dxt` file
3. **Click "Install"** in Claude Desktop
4. **Configure** your Pictory API credentials in the extension settings

The extension will automatically handle dependency management and configuration!

## 🔧 Configuration

After installing the extension, you'll be prompted to configure these settings:

- **Client ID**: Your Pictory API Client ID
- **Client Secret**: Your Pictory API Client Secret
- **User ID**: Your Pictory User ID
- **API Base URL**: (Optional) Defaults to `https://api.pictory.ai/pictoryapis/v1`

> 💡 **Get your API credentials** from your [Pictory Developer Account](https://pictory.ai/api)

## ✨ Features

This MCP server provides 9 powerful 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

### Option 2: Traditional MCP Installation

For users who prefer manual MCP server configuration:

#### Global Installation
```bash
npm install -g @pictory/pictory-mcp-server
```

#### Direct Usage
```bash
npx @pictory/pictory-mcp-server
```

#### Claude Desktop Configuration
Add to your Claude Desktop configuration file:

```json
{
  "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"
      }
    }
  }
}
```

---

## 🎬 Usage Examples

### Create a Marketing Video
```
User: Create a video with three scenes: "Welcome to our new product", "Here's how it works", and "Get started today"

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

[Claude uses create-storyboard tool with your script]
```

### Use a Video Template
```
User: Show me available video templates and create a video using one

Claude: I'll first get all available templates, then help you create a video using one.

[Claude uses get-all-video-templates, then create-storyboard-from-template]
```

## 🛠️ API Tools Reference

### 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

## 🔄 Complete Video Workflow

1. **Create a storyboard:**
```javascript
// 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"
}
```

2. **Wait for storyboard completion and get preview:**
```javascript
// Tool: poll-storyboard-job-status
{ "jobId": "storyboard-job-123" }

// Tool: get-storyboard-preview
{ "jobId": "storyboard-job-123" }
```

3. **Render the final video:**
```javascript
// Tool: render-video
{ "storyboardJobId": "storyboard-job-123" }
```

4. **Wait for video completion and get URL:**
```javascript
// Tool: poll-video-job-status
{ "jobId": "video-job-456" }

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

## 🔒 Security & Privacy

- **Local Processing**: All video creation requests are processed through Pictory's secure API
- **Credential Storage**: API credentials are securely stored in your system's keychain when using the Desktop Extension
- **No Data Retention**: This MCP server doesn't store or cache your video content



## 🐛 Error Handling

The server includes comprehensive error handling for:
- Missing environment variables
- API authentication failures
- Network connectivity issues
- Job timeout scenarios
- Malformed requests

## 📝 License

See [LICENSE.txt](./LICENSE.txt) for license information.

## 🆘 Support

- **Documentation**: [GitHub Repository](https://github.com/pictory/mcp-server)
- **Issues**: [GitHub Issues](https://github.com/pictory/mcp-server/issues)
- **Pictory Support**: [Pictory Help Center](https://pictory.ai/support)

## 🌟 Example Claude Interactions

Once configured with Claude Desktop, you can interact with the Pictory MCP server naturally:

### 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]
```

### Using Templates

```
You: Show me available video templates and create a promotional video

Claude: I'll first get all available templates to show you the options, then help you create a promotional video.

[Claude uses get-all-video-templates and create-storyboard-from-template tools]
```


## LICENSE

See LICENSE.txt