Skip to content
Back to search

sora-mcp

An MCP server to use Sora video generation APIs

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/doriandarko--sora-mcp/badge.svg)](/listings/doriandarko--sora-mcp)

HTML

<a href="/listings/doriandarko--sora-mcp"><img src="/api/listings/doriandarko--sora-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Clone the repository:

git clone https://github.com/Doriandarko/sora-mcp
cd sora-mcp

2. Install dependencies:

npm install

3. Build the project:

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 369 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Sora MCP Server
  2. A Model Context Protocol (MCP) server that integrates with OpenAI's Sora 2 API for video generation and remixing.
  3. ## Features
  4. - **Create Videos**: Generate videos from text prompts using Sora 2
  5. - **Remix Videos**: Create variations of existing videos with new prompts
  6. - **Video Status**: Check the status and progress of video generation jobs
  7. ## Prerequisites
  8. - Node.js 18+
  9. - OpenAI API key with Sora access
  10. - An MCP-compatible client (Claude, Cursor, VS Code, etc.)
  11. ## Installation
  12. 1. Clone the repository:
  13. ```bash
  14. git clone https://github.com/Doriandarko/sora-mcp
  15. cd sora-mcp
  16. ```
  17. 2. Install dependencies:
  18. ```bash
  19. npm install
  20. ```
  21. 3. Build the project:
  22. ```bash
  23. npm run build
  24. ```
  25. 4. Configure for Claude Desktop:
  26. - Copy `claude_desktop_config.example.json` to `~/Library/Application Support/Claude/claude_desktop_config.json`
  27. - Update the `args` path to match your installation directory
  28. - Add your OpenAI API key to the `OPENAI_API_KEY` field
  29. - Optionally set `DOWNLOAD_DIR` to your preferred download folder
  30. ## Server Architecture
  31. This project includes **two server implementations** for different use cases:
  32. ### 📱 `stdio-server.ts` - For Claude Desktop
  33. - **Transport:** stdio (Standard Input/Output)
  34. - **Use case:** Local process communication
  35. - **How it works:** Claude Desktop spawns this as a child process
  36. - **Benefits:** Fast, secure, no network needed
  37. - **Used by:** Claude Desktop
  38. ### 🌐 `server.ts` - For Remote Access
  39. - **Transport:** HTTP/Streamable HTTP
  40. - **Use case:** Remote clients, web-based tools
  41. - **How it works:** Runs as HTTP server on port 3000
  42. - **Benefits:** Network accessible, multiple clients
  43. - **Used by:** MCP Inspector, VS Code, Cursor, browsers
  44. **Why two servers?** Different MCP clients use different transports. This separation keeps the code clean and optimized for each transport type.
  45. ## Usage
  46. ### For Claude Desktop (stdio mode)
  47. Claude Desktop will automatically start the server when configured. Just make sure:
  48. 1. Your `.env` file has your `OPENAI_API_KEY`
  49. 2. Restart Claude Desktop after updating the config
  50. The config uses `src/stdio-server.ts` which communicates via stdio.
  51. ### For HTTP Mode (MCP Inspector, web clients)
  52. Run the server in development mode with auto-reload:
  53. ```bash
  54. npm run dev
  55. ```
  56. Or in production mode:
  57. ```bash
  58. npm run build
  59. npm start
  60. ```
  61. ## Connecting to MCP Clients
  62. ### Claude Desktop
  63. The server is already configured!
  64. **Setup:**
  65. The configuration is at: `~/Library/Application Support/Claude/claude_desktop_config.json`
  66. It uses the compiled server and passes your API key via environment variables:
  67. ```json
  68. {
  69. "mcpServers": {
  70. "sora-server": {
  71. "command": "node",
  72. "args": ["/ABSOLUTE/PATH/TO/sora-mcp/dist/stdio-server.js"],
  73. "env": {
  74. "OPENAI_API_KEY": "your-openai-api-key-here",
  75. "DOWNLOAD_DIR": "/Users/yourname/Downloads/sora"
  76. }
  77. }
  78. }
  79. }
  80. ```
  81. See `claude_desktop_config.example.json` for a complete example.
  82. **Environment Variables:**
  83. - `OPENAI_API_KEY` (required) - Your OpenAI API key
  84. - `DOWNLOAD_DIR` (optional) - Custom download folder (defaults to ~/Downloads)
  85. **To use:**
  86. 1. Restart Claude Desktop (Cmd+Q then relaunch)
  87. 2. The Sora tools will appear automatically!
  88. ### MCP Inspector (for testing)
  89. Test your server with the MCP Inspector:
  90. ```bash
  91. npx @modelcontextprotocol/inspector
  92. ```
  93. Then connect to: `http://localhost:3000/mcp`
  94. ### Claude Code
  95. ```bash
  96. claude mcp add --transport http sora-server http://localhost:3000/mcp
  97. ```
  98. ### VS Code
  99. ```bash
  100. code --add-mcp '{"name":"sora-server","type":"http","url":"http://localhost:3000/mcp"}'
  101. ```
  102. ### Cursor
  103. Add to your Cursor MCP settings with stdio transport (similar to Claude Desktop configuration above).
  104. ## Available Tools
  105. ### create-video
  106. Generate a video from a text prompt.
  107. **Parameters:**
  108. - `prompt` (required): Text description of the video to generate
  109. - `model` (optional): Model to use (default: "sora-2")
  110. - `seconds` (optional): Video duration in seconds (default: "4")
  111. - `size` (optional): Resolution as "widthxheight" (default: "720x1280")
  112. - `input_reference` (optional): Path to reference image/video
  113. **Example:**
  114. ```javascript
  115. {
  116. "prompt": "A calico cat playing a piano on stage",
  117. "model": "sora-2",
  118. "seconds": "8",
  119. "size": "1024x1808"
  120. }
  121. ```
  122. ### get-video-status
  123. Check the status and progress of a video generation job.
  124. **Parameters:**
  125. - `video_id` (required): ID of the video to check
  126. **Example:**
  127. ```javascript
  128. {
  129. "video_id": "video_123"
  130. }
  131. ```
  132. **Returns:** Video status including `progress` (0-100), `status` (queued/processing/completed), and completion timestamps.
  133. ### list-videos
  134. List all your video generation jobs with pagination.
  135. **Parameters:**
  136. - `limit` (optional): Number of videos to retrieve (default: 20)
  137. - `after` (optional): Pagination cursor - get videos after this ID
  138. - `order` (optional): Sort order "asc" or "desc" (default: "desc")
  139. **Example:**
  140. ```javascript
  141. {
  142. "limit": 10,
  143. "order": "desc"
  144. }
  145. ```
  146. ### download-video
  147. Get a curl command to manually download a completed video.
  148. **Parameters:**
  149. - `video_id` (required): ID of the video to download
  150. - `variant` (optional): Which format to download (defaults to MP4)
  151. **Example:**
  152. ```javascript
  153. {
  154. "video_id": "video_123"
  155. }
  156. ```
  157. **Returns:** Ready-to-use curl command with authentication for downloading the video.
  158. ### save-video ⭐ (Auto-Download)
  159. Automatically download and save a completed video to your computer.
  160. **Parameters:**
  161. - `video_id` (required): ID of the video to save
  162. - `output_path` (optional): Directory to save to (defaults to ~/Downloads)
  163. - `filename` (optional): Custom filename (defaults to video_id.mp4)
  164. **Example:**
  165. ```javascript
  166. {
  167. "video_id": "video_123",
  168. "filename": "my-cat-video.mp4"
  169. }
  170. ```
  171. **Returns:** File path where video was saved. No manual commands needed!
  172. ### remix-video
  173. Create a remix of an existing video with a new prompt.
  174. **Parameters:**
  175. - `video_id` (required): ID of the completed video to remix
  176. - `prompt` (required): New text prompt for the remix
  177. **Example:**
  178. ```javascript
  179. {
  180. "video_id": "video_123",
  181. "prompt": "Extend the scene with the cat taking a bow to the cheering audience"
  182. }
  183. ```
  184. ### delete-video
  185. Delete a video job and its assets.
  186. **Parameters:**
  187. - `video_id` (required): ID of the video to delete
  188. **Example:**
  189. ```javascript
  190. {
  191. "video_id": "video_123"
  192. }
  193. ```
  194. ## Typical Workflow
  195. 1. **Create a video** → Get back a `video_id`
  196. ```
  197. "Create a video of a sunset over mountains"
  198. ```
  199. 2. **Check status** → Monitor progress
  200. ```
  201. "Check the status of video video_123"
  202. ```
  203. 3. **Save when ready** → Auto-download the video file
  204. ```
  205. "Save video video_123"
  206. ```
  207. Claude will automatically download it to your Downloads folder!
  208. 4. **Clean up** → Delete old videos
  209. ```
  210. "Delete video video_123"
  211. ```
  212. ## API Response Format
  213. ### Video Job Response
  214. ```json
  215. {
  216. "id": "video_123",
  217. "object": "video",
  218. "model": "sora-2",
  219. "status": "queued",
  220. "progress": 0,
  221. "created_at": 1712697600,
  222. "size": "1024x1808",
  223. "seconds": "8",
  224. "quality": "standard"
  225. }
  226. ```
  227. ### Remix Response
  228. ```json
  229. {
  230. "id": "video_456",
  231. "object": "video",
  232. "model": "sora-2",
  233. "status": "queued",
  234. "progress": 0,
  235. "created_at": 1712698600,
  236. "size": "720x1280",
  237. "seconds": "8",
  238. "remixed_from_video_id": "video_123"
  239. }
  240. ```
  241. ## Error Handling
  242. The server includes comprehensive error handling:
  243. - Missing API key validation on startup
  244. - API error responses with detailed messages
  245. - Graceful error returns in tool responses
  246. ## Development
  247. ### Project Structure
  248. ```
  249. sora-mcp/
  250. ├── src/
  251. │ └── server.ts # Main server implementation
  252. ├── dist/ # Compiled JavaScript (generated)
  253. ├── package.json # Dependencies and scripts
  254. ├── tsconfig.json # TypeScript configuration
  255. ├── .env # Environment variables (not in git)
  256. └── README.md # This file
  257. ```
  258. ### Scripts
  259. - `npm run dev` - Run in development mode with tsx
  260. - `npm run build` - Compile TypeScript to JavaScript
  261. - `npm start` - Run compiled JavaScript
  262. ## Environment Variables
  263. - `OPENAI_API_KEY` (required) - Your OpenAI API key
  264. - `PORT` (optional) - Server port (default: 3000)
  265. ## License
  266. MIT
  267. ## Resources
  268. - [Model Context Protocol Documentation](https://modelcontextprotocol.io)
  269. - [OpenAI Sora API Documentation](https://platform.openai.com/docs/api-reference/videos)
  270. - [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.