Metadata-Version: 2.4
Name: narrateai-mcp
Version: 0.7.0
Summary: MCP server for NarrateAI - video narration, transcription, dubbing, TTS, and document generation
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: fastmcp[tasks]>=3.0.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: uvicorn>=0.30.0

# NarrateAI MCP Server

Add AI video narration, transcription, translation, and dubbing to any AI assistant. NarrateAI's MCP server lets Claude, Cursor, and other MCP-compatible tools process videos through natural conversation.

## What You Can Do

- **Narrate silent videos** — AI writes a timed script and generates voiceover with natural-sounding voices
- **Transcribe speech** — Extract text from videos with existing audio (meetings, podcasts, lectures)
- **Translate transcripts** — Translate video transcripts between 11+ languages
- **Dub videos** — Clone the speaker's voice and re-speak in another language
- **Generate documents** — Turn screencasts into guides, tutorials, and product docs
- **Edit before narrating** — Review and refine AI-generated scripts before producing the final video
- **Batch process** — Narrate, transcribe, or dub up to 5 videos in parallel
- **Browse video library** — Access and re-use previously processed videos

## Quick Start

### 1. Get an API Key

Sign up at [narrateai.app](https://narrateai.app) and purchase MCP credits from the API section.

### 2. Install

```bash
pip install narrateai-mcp
```

### 3. Connect to Cursor

Add to your `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "narrateai": {
      "command": "narrateai-mcp",
      "env": {
        "NARRATEAI_API_BASE_URL": "https://api.narrateai.app",
        "NARRATEAI_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

Restart Cursor, and you're ready. Try: *"Narrate this video with the male1 voice: https://example.com/demo.mp4"*

### 4. Connect to Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on Mac):

```json
{
  "mcpServers": {
    "narrateai": {
      "command": "narrateai-mcp",
      "env": {
        "NARRATEAI_API_BASE_URL": "https://api.narrateai.app",
        "NARRATEAI_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

## Available Tools

### Video Narration
| Tool | Description |
|------|-------------|
| `generate_narration_script` | Generate a timed AI narration script for a silent video (text only) |
| `narrate_video_full` | Produce a full narrated video with AI voiceover |
| `continue_to_full_video` | Turn an existing script into a narrated video |
| `narrate_batch` | Narrate up to 5 videos in parallel |
| `batch_generate_scripts` | Generate scripts for multiple videos in parallel |

### Transcription & Translation
| Tool | Description |
|------|-------------|
| `transcribe_video` | Extract speech-to-text from a video with existing audio |
| `transcribe_and_translate` | Transcribe and translate a video's speech |
| `translate_existing_video` | Translate the transcript of a previously processed video |
| `batch_transcribe` | Transcribe multiple videos in parallel |

### Dubbing
| Tool | Description |
|------|-------------|
| `dub_video_full` | Full auto-dubbing with voice cloning into another language |
| `batch_dub` | Dub multiple videos in parallel |

### Documents & Library
| Tool | Description |
|------|-------------|
| `generate_document` | Generate a structured document (guide, tutorial, docs) from a video |
| `list_videos` | Browse your video library |
| `update_transcript` | Edit narration scripts before producing the final video |

### Utilities
| Tool | Description |
|------|-------------|
| `get_job_result` | Check job status or retrieve results |
| `get_upload_url` | Get a signed upload URL for local files (remote mode) |
| `abandon_job` | Cancel a running job |

## Available Voices

**AI Voices:**
- **male1** (default, fastest generation)
- **female1** (default, fastest generation)
- **female2**, **female3**, **female4**
- **male2**, **male3**

**Voice Cloning:**
Provide your own audio file and NarrateAI clones your voice for the narration. Pass a local file path or URL as `voice_sample` to `narrate_video_full` or `continue_to_full_video`.

## Supported Languages

en, es, fr, de, it, pt, ru, zh, yue, ja, ko — and others via Whisper fallback.

## Example Conversations

**Narrate a screencast:**
> "I have a silent demo video. Can you narrate it with the male1 voice?"

**Transcribe a meeting:**
> "Transcribe this meeting recording — it's in Spanish: meeting.mp4"

**Dub a video:**
> "Dub this English video into French, keep the background music"

**Generate product docs:**
> "Create a tutorial guide from this screencast of our new feature"

**Clone your voice:**
> "Narrate this video using my voice — here's a recording: voice.wav"

**Translate and re-narrate:**
> "Take my narrated Messi video, translate it to Hindi, and re-narrate with male1"

## Remote / HTTP Mode

For cloud deployments (Smithery, Apify, or self-hosted), run the server in HTTP mode:

```bash
narrateai-mcp --transport http --port 8080
```

The server accepts API keys via the `x-api-key` HTTP header for remote authentication.

## Troubleshooting

- **"API key required"** — Set `NARRATEAI_API_KEY` in your MCP config or pass `api_key` to any tool.
- **"Video file not found"** — Verify the local file path exists. For remote mode, use `get_upload_url` first.
- **429 / rate limit** — You've used all your MCP credits. Purchase more at [narrateai.app](https://narrateai.app).
- **Timeout** — Long videos may take more time. Use `get_job_result` to check progress.

## Links

- [NarrateAI](https://narrateai.app) — Sign up and get API credits
- [SKILL.md](https://github.com/RafayF1/narrateai-skill) — AI skill file for enhanced workflow guidance
