# Sora Mcp

> An MCP server to use Sora video generation APIs

- **Type:** MCP server
- **Install:** `agentstack add mcp-doriandarko-sora-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Doriandarko](https://agentstack.voostack.com/s/doriandarko)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Doriandarko](https://github.com/Doriandarko)
- **Source:** https://github.com/Doriandarko/sora-mcp

## Install

```sh
agentstack add mcp-doriandarko-sora-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Sora MCP Server

A Model Context Protocol (MCP) server that integrates with OpenAI's Sora 2 API for video generation and remixing.

## Features

- **Create Videos**: Generate videos from text prompts using Sora 2
- **Remix Videos**: Create variations of existing videos with new prompts
- **Video Status**: Check the status and progress of video generation jobs

## Prerequisites

- Node.js 18+ 
- OpenAI API key with Sora access
- An MCP-compatible client (Claude, Cursor, VS Code, etc.)

## Installation

1. Clone the repository:
```bash
git clone https://github.com/Doriandarko/sora-mcp
cd sora-mcp
```

2. Install dependencies:
```bash
npm install
```

3. Build the project:
```bash
npm run build
```

4. Configure for Claude Desktop:
   - Copy `claude_desktop_config.example.json` to `~/Library/Application Support/Claude/claude_desktop_config.json`
   - Update the `args` path to match your installation directory
   - Add your OpenAI API key to the `OPENAI_API_KEY` field
   - Optionally set `DOWNLOAD_DIR` to your preferred download folder

## Server Architecture

This project includes **two server implementations** for different use cases:

### 📱 `stdio-server.ts` - For Claude Desktop
- **Transport:** stdio (Standard Input/Output)
- **Use case:** Local process communication
- **How it works:** Claude Desktop spawns this as a child process
- **Benefits:** Fast, secure, no network needed
- **Used by:** Claude Desktop

### 🌐 `server.ts` - For Remote Access
- **Transport:** HTTP/Streamable HTTP  
- **Use case:** Remote clients, web-based tools
- **How it works:** Runs as HTTP server on port 3000
- **Benefits:** Network accessible, multiple clients
- **Used by:** MCP Inspector, VS Code, Cursor, browsers

**Why two servers?** Different MCP clients use different transports. This separation keeps the code clean and optimized for each transport type.

## Usage

### For Claude Desktop (stdio mode)

Claude Desktop will automatically start the server when configured. Just make sure:
1. Your `.env` file has your `OPENAI_API_KEY`
2. Restart Claude Desktop after updating the config

The config uses `src/stdio-server.ts` which communicates via stdio.

### For HTTP Mode (MCP Inspector, web clients)

Run the server in development mode with auto-reload:

```bash
npm run dev
```

Or in production mode:

```bash
npm run build
npm start
```

## Connecting to MCP Clients

### Claude Desktop

The server is already configured! 

**Setup:**
The configuration is at: `~/Library/Application Support/Claude/claude_desktop_config.json`

It uses the compiled server and passes your API key via environment variables:
```json
{
  "mcpServers": {
    "sora-server": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/sora-mcp/dist/stdio-server.js"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key-here",
        "DOWNLOAD_DIR": "/Users/yourname/Downloads/sora"
      }
    }
  }
}
```

See `claude_desktop_config.example.json` for a complete example.

**Environment Variables:**
- `OPENAI_API_KEY` (required) - Your OpenAI API key
- `DOWNLOAD_DIR` (optional) - Custom download folder (defaults to ~/Downloads)

**To use:**
1. Restart Claude Desktop (Cmd+Q then relaunch)
2. The Sora tools will appear automatically!

### MCP Inspector (for testing)

Test your server with the MCP Inspector:

```bash
npx @modelcontextprotocol/inspector
```

Then connect to: `http://localhost:3000/mcp`

### Claude Code

```bash
claude mcp add --transport http sora-server http://localhost:3000/mcp
```

### VS Code

```bash
code --add-mcp '{"name":"sora-server","type":"http","url":"http://localhost:3000/mcp"}'
```

### Cursor

Add to your Cursor MCP settings with stdio transport (similar to Claude Desktop configuration above).

## Available Tools

### create-video

Generate a video from a text prompt.

**Parameters:**
- `prompt` (required): Text description of the video to generate
- `model` (optional): Model to use (default: "sora-2")
- `seconds` (optional): Video duration in seconds (default: "4")
- `size` (optional): Resolution as "widthxheight" (default: "720x1280")
- `input_reference` (optional): Path to reference image/video

**Example:**
```javascript
{
  "prompt": "A calico cat playing a piano on stage",
  "model": "sora-2",
  "seconds": "8",
  "size": "1024x1808"
}
```

### get-video-status

Check the status and progress of a video generation job.

**Parameters:**
- `video_id` (required): ID of the video to check

**Example:**
```javascript
{
  "video_id": "video_123"
}
```

**Returns:** Video status including `progress` (0-100), `status` (queued/processing/completed), and completion timestamps.

### list-videos

List all your video generation jobs with pagination.

**Parameters:**
- `limit` (optional): Number of videos to retrieve (default: 20)
- `after` (optional): Pagination cursor - get videos after this ID
- `order` (optional): Sort order "asc" or "desc" (default: "desc")

**Example:**
```javascript
{
  "limit": 10,
  "order": "desc"
}
```

### download-video

Get a curl command to manually download a completed video.

**Parameters:**
- `video_id` (required): ID of the video to download
- `variant` (optional): Which format to download (defaults to MP4)

**Example:**
```javascript
{
  "video_id": "video_123"
}
```

**Returns:** Ready-to-use curl command with authentication for downloading the video.

### save-video ⭐ (Auto-Download)

Automatically download and save a completed video to your computer.

**Parameters:**
- `video_id` (required): ID of the video to save
- `output_path` (optional): Directory to save to (defaults to ~/Downloads)
- `filename` (optional): Custom filename (defaults to video_id.mp4)

**Example:**
```javascript
{
  "video_id": "video_123",
  "filename": "my-cat-video.mp4"
}
```

**Returns:** File path where video was saved. No manual commands needed!

### remix-video

Create a remix of an existing video with a new prompt.

**Parameters:**
- `video_id` (required): ID of the completed video to remix
- `prompt` (required): New text prompt for the remix

**Example:**
```javascript
{
  "video_id": "video_123",
  "prompt": "Extend the scene with the cat taking a bow to the cheering audience"
}
```

### delete-video

Delete a video job and its assets.

**Parameters:**
- `video_id` (required): ID of the video to delete

**Example:**
```javascript
{
  "video_id": "video_123"
}
```

## Typical Workflow

1. **Create a video** → Get back a `video_id`
   ```
   "Create a video of a sunset over mountains"
   ```

2. **Check status** → Monitor progress
   ```
   "Check the status of video video_123"
   ```

3. **Save when ready** → Auto-download the video file
   ```
   "Save video video_123"
   ```
   Claude will automatically download it to your Downloads folder!

4. **Clean up** → Delete old videos
   ```
   "Delete video video_123"
   ```

## API Response Format

### Video Job Response

```json
{
  "id": "video_123",
  "object": "video",
  "model": "sora-2",
  "status": "queued",
  "progress": 0,
  "created_at": 1712697600,
  "size": "1024x1808",
  "seconds": "8",
  "quality": "standard"
}
```

### Remix Response

```json
{
  "id": "video_456",
  "object": "video",
  "model": "sora-2",
  "status": "queued",
  "progress": 0,
  "created_at": 1712698600,
  "size": "720x1280",
  "seconds": "8",
  "remixed_from_video_id": "video_123"
}
```

## Error Handling

The server includes comprehensive error handling:

- Missing API key validation on startup
- API error responses with detailed messages
- Graceful error returns in tool responses

## Development

### Project Structure

```
sora-mcp/
├── src/
│   └── server.ts       # Main server implementation
├── dist/               # Compiled JavaScript (generated)
├── package.json        # Dependencies and scripts
├── tsconfig.json       # TypeScript configuration
├── .env               # Environment variables (not in git)
└── README.md          # This file
```

### Scripts

- `npm run dev` - Run in development mode with tsx
- `npm run build` - Compile TypeScript to JavaScript
- `npm start` - Run compiled JavaScript

## Environment Variables

- `OPENAI_API_KEY` (required) - Your OpenAI API key
- `PORT` (optional) - Server port (default: 3000)

## License

MIT

## Resources

- [Model Context Protocol Documentation](https://modelcontextprotocol.io)
- [OpenAI Sora API Documentation](https://platform.openai.com/docs/api-reference/videos)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Doriandarko](https://github.com/Doriandarko)
- **Source:** [Doriandarko/sora-mcp](https://github.com/Doriandarko/sora-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-doriandarko-sora-mcp
- Seller: https://agentstack.voostack.com/s/doriandarko
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.