Ozor MCP Server

An MCP (Model Context Protocol) server that wraps the Ozor AI Video Generation API, exposing its full capabilities as MCP tools for Claude Desktop, Claude.ai, VS Code, and any other MCP-compatible client.

Generate AI videos from a prompt or from a document (PDF / PPTX / DOCX / web URL), iterate with the AI agent, export ready-to-share MP4s, and get ready-to-paste embed code — all from natural language inside Claude.

Tools

Video

| Tool | Description | Type | |------|-------------|------| | generate_video | Generate a new AI video from a text prompt (async — returns a jobId) | Write | | list_videos | List videos created via the API | Read | | get_video | Get full status, export status, and download/share URLs for a video | Read | | export_video | Trigger an MP4 export (set isPublic for a permanent shareable link) | Write | | send_message | Send a natural-language edit instruction to the AI agent (async) | Write | | get_job | Poll an agent job's status | Read | | wait_for_job | Block until an agent job finishes, then return the result | Read | | wait_for_export | Block until an MP4 export finishes, then return download/share URLs | Read | | get_embed_code | Produce share link + <iframe> / <video> embed snippets for a finished video | Read |

Document-to-Video

| Tool | Description | Type | |------|-------------|------| | list_voices | List available TTS narration voices | Read | | analyze_document | Turn a PDF / PPTX / DOCX / URL into an editable scene-by-scene plan | Write | | get_plan | Retrieve a document plan | Read | | update_plan | Edit a plan's scenes / voiceover / voice settings before generating | Write | | generate_from_plan | Render a plan into a video project (consumes the SSE progress stream) | Write |

Typical workflows

1 — Prompt → video → shareable embed

"Create a 20-second product teaser for a wireless headphone, export it public, and give me the embed code."

Claude calls generate_video with export: true, exportIsPublic: true → wait_for_export → get_embed_code. You get a /share/{code} page link and an <iframe> snippet pointing at /embed/{code}.

2 — Document → video

"Turn this pitch deck PDF into a 45-second narrated video with the Nova voice."

Claude calls analyze_document (file or URL) → optionally update_plan (set voiceSettings.voiceId: "nova") → generate_from_plan → export_video → get_embed_code.

3 — Iterate on an existing video

"Add our logo to the top-right of every scene, then re-export in 1080p."

Claude calls send_message → wait_for_job → export_video with isPublic: true → get_embed_code.

How API keys work

This server is multi-user — it does not hold a shared API key. Each user provides their own Ozor API key (sk_live_...), created from the dashboard at ozor.ai (Settings → API Keys).

| Transport | How you provide your Ozor API key | |-----------|-----------------------------------| | STDIO (local) | Set OZOR_API_KEY in the env passed to the process | | HTTP + header (Claude Desktop, Claude Code) | Send X-Ozor-Api-Key: your_key header on every request | | HTTP + OAuth (Claude.ai web/mobile) | Connect via OAuth — paste your key once on the consent screen |

With STDIO and header transports the server only forwards the key to the Ozor API as X-API-Key; it never stores it. With OAuth the key is encrypted at rest (AES-256-GCM) and exchanged for short-lived bearer tokens — see below.

Connecting from Claude.ai (OAuth)

Claude.ai's web and mobile apps can't send a custom header, so the server also runs as an OAuth 2.1 authorization server. To connect, add the custom connector URL (https://mcp.ozor.ai/mcp) in Settings → Connectors. Claude.ai registers itself automatically, then opens a consent screen where you paste your Ozor API key once. After that, Claude.ai holds an access token; your raw key is stored only in encrypted form and never sent to Claude.

OAuth is active only when the deployment sets OAUTH_ISSUER_URL and TOKEN_ENC_KEY (see DEPLOYMENT-CONSOLE.md). The X-Ozor-Api-Key header path keeps working unchanged for Claude Desktop / Code.

Quick start — Remote HTTP (recommended)

Connect to the hosted endpoint. No installation required.

{
  "mcpServers": {
    "ozor": {
      "url": "https://mcp.ozor.ai/mcp",
      "headers": {
        "X-Ozor-Api-Key": "sk_live_your_key_here"
      }
    }
  }
}

Config file location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Local setup (STDIO)

npm install
npm run build

# test with MCP Inspector
OZOR_API_KEY=sk_live_your_key npx @modelcontextprotocol/inspector node build/index.js

Then add to claude_desktop_config.json:

{
  "mcpServers": {
    "ozor": {
      "command": "node",
      "args": ["/absolute/path/to/ozor-MCP/build/index.js"],
      "env": { "OZOR_API_KEY": "sk_live_your_key_here" }
    }
  }
}

Environment variables

| Variable | Required | Notes | |----------|----------|-------| | OZOR_API_KEY | STDIO mode only | Your Ozor API key. HTTP mode reads the key per-request from the X-Ozor-Api-Key header instead. | | PORT | HTTP mode only | When set, the server starts in HTTP mode on this port. When unset, it runs in STDIO mode. | | OZOR_BASE_URL | No | Override the Ozor API base URL (default https://ozor.ai). Useful for staging. | | OAUTH_ISSUER_URL | For OAuth | The public HTTPS URL clients connect to (e.g. https://mcp.ozor.ai). Enables the OAuth flow. Must match the URL users actually use. | | TOKEN_ENC_KEY | For OAuth | Base64 of 32 random bytes — encrypts stored Ozor keys at rest. Required alongside OAUTH_ISSUER_URL. | | FIRESTORE_DATABASE_ID | No | Non-default Firestore database id for OAuth state (default (default)). |

OAuth mode (HTTP) needs Firestore for token storage — the Cloud Run service account requires the roles/datastore.user IAM role.

Notes on specific tools

• analyze_document accepts a source three ways: a web url, a local filePath (STDIO mode only — the file is read from disk), or fileBase64 + fileName (works in any transport, including remote HTTP).
• generate_from_plan consumes the backend's Server-Sent Events progress stream internally and returns once the done event arrives, including the new projectId. Long renders can take minutes — tune timeoutSeconds (default 600).
• get_embed_code requires a completed public export. Generate with exportIsPublic: true, or call export_video with isPublic: true. The <iframe> it returns points at the https://ozor.ai/embed/{shareCode} route.

Deployment

See DEPLOYMENT.md for the full plan to host the HTTP transport on Google Cloud (Cloud Run) at mcp.ozor.ai, plus the one frontend route (/embed/{shareCode}) the embed feature depends on.

Support

For help or issues: [email protected]

Privacy

https://ozor.ai/privacy