ozor-mcp-server

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: [e-mail]

Privacy

https://ozor.ai/privacy