Sora FastMCP Server

Clean, simple MCP server for Sora image & video generation using FastMCP.

🚀 Quick Start

Option 1: Docker (Recommended)

# 1. Create .env file
copy env.example .env
# Edit .env and add your OPENAI_API_KEY

# 2. Start both services
docker compose up -d

# 3. Access services
# - MCP Server: http://localhost:8077/sse
# - API Docs: http://localhost:8088/docs

Option 2: Local Python

# 1. Install dependencies
pip install -r requirements.txt

# 2. Create .env file
copy env.example .env
# Edit .env and add your OPENAI_API_KEY

# 3. Run MCP server
fastmcp run server.py --transport sse --host 0.0.0.0 --port 8077

# 4. Run docs API (optional, separate terminal)
python docs_api.py

📖 Documentation

Interactive API Docs (Swagger)

http://localhost:8088/docs 📚

The documentation API provides:

• ✅ Connection instructions for Cursor/Claude Desktop
• ✅ Tool schemas with detailed parameter info
• ✅ Copy-paste config snippets
• ✅ Setup guide for sharing with friends

Quick Links:

• 🔗 Connection Config: http://localhost:8088/api/config
• 🛠️ Tools List: http://localhost:8088/api/tools
• ℹ️ Server Info: http://localhost:8088/api/info

🔧 Cursor Configuration

Visit http://localhost:8088/api/config for ready-to-use config, or add manually:

Edit ~/.cursor/mcp.json (Windows: C:\Users\YourName\.cursor\mcp.json):

{
  "mcpServers": {
    "sora": {
      "type": "sse",
      "url": "http://localhost:8077/sse"
    }
  }
}

Then restart Cursor and look for the GREEN dot next to "sora"! ✅

🎯 Available Tools

1. generate_image

Generate images with DALL-E or Sora image models.

Parameters:

• prompt (required): Image description
• model: "dall-e-3" (default), "dall-e-2"
• size: "1024x1024" (default), "1792x1024", "1024x1792", etc.
• quality: "standard" (default) or "hd"
• n: Number of images (1-10)

Example:

Generate an image of a sunset over mountains

2. generate_video

Generate videos with Sora models.

Parameters:

• prompt (required): Video description
• model: "sora-2" (default), "sora-2-pro"
• duration: 4-30 seconds (default: 10)
• aspect_ratio: "16:9" (default), "9:16", "1:1", "4:3", "3:4"
• with_audio: boolean (default: false)

Example:

Generate a video of ocean waves crashing on a beach at sunset

3. check_api_status

Check OpenAI API connection and available models.

Example:

Check API status

🐳 Docker Commands

# Start services
docker compose up -d

# View logs
docker compose logs -f

# Stop services
docker compose down

# Rebuild after code changes
docker compose build
docker compose up -d

# View running services
docker compose ps

🌐 Sharing with Friends

To let friends in different locations use your MCP server:

Option 1: ngrok (Easiest)

# Install ngrok: https://ngrok.com/download
ngrok http 8077

Your friend adds to their mcp.json:

{
  "mcpServers": {
    "sora": {
      "type": "sse",
      "url": "https://your-ngrok-url.ngrok.io/sse"
    }
  }
}

Option 2: Cloudflare Tunnel

# Install: https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/installation/
cloudflared tunnel --url http://localhost:8077

Option 3: Port Forwarding

1. Forward port 8077 on your router
2. Share your public IP: http://YOUR_PUBLIC_IP:8077/sse

📦 Services

1. MCP Server (Port 8077)

• Purpose: MCP SSE endpoint for AI assistants
• Endpoint: http://localhost:8077/sse
• Used by: Cursor, Claude Desktop
• Status: Check with Cursor's MCP server list

2. Documentation API (Port 8088)

• Purpose: Human-readable docs & connection guide
• Swagger UI: http://localhost:8088/docs
• Used by: You and your friends to get setup instructions
• Endpoints:
  • /api/config - Copy-paste configuration
  • /api/tools - Tool documentation
  • /api/info - Server information

🔑 Environment Variables

Create .env file (see env.example):

OPENAI_API_KEY=sk-...          # Required: Your OpenAI API key
OPENAI_BASE_URL=               # Optional: Custom API endpoint

✅ Troubleshooting

MCP Server shows RED/ORANGE in Cursor

1. Check server is running: docker compose ps
2. Verify config URL is correct: http://localhost:8077/sse
3. Restart Cursor completely
4. Check logs: docker compose logs sora-mcp

Can't access Swagger docs

1. Check docs service: docker compose ps
2. Try: http://localhost:8088/docs
3. Check logs: docker compose logs sora-docs

Friend can't connect

1. Verify MCP server accessible from their network
2. Test endpoint: curl http://YOUR_URL/sse
3. Check firewall/router settings
4. Consider using ngrok for easier setup

📝 Notes

• FastMCP handles all MCP protocol complexity
• Separate services keep concerns cleanly separated
• Docker Compose manages both services together
• Port 8077: MCP SSE (for AI assistants)
• Port 8088: Swagger Docs (for humans)

🎉 Success!

When everything works:

• ✅ Cursor shows GREEN dot for "sora"
• ✅ You see 3 tools available
• ✅ You can generate images and videos
• ✅ Friends can connect using your shared URL
• ✅ Swagger docs show connection instructions

Enjoy! 🚀

CI/CD is configured!