Metadata-Version: 2.4
Name: narrateai-mcp
Version: 0.7.7
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 |
| `list_voices` | List saved cloned voices (id and name) |
| `list_elevenlabs_voices` | List voices on a connected ElevenLabs account |
| `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** (pass as `voice_type`):
- **male1** (fastest default)
- **female1** (fastest default)
- **male2**, **male3**, **male4**, **male5**, **male6**
- **female2**, **female3**, **female4**, **female5**

**ElevenLabs:** the user connects their account in NarrateAI (One-Time, AppSumo, Growth, Pro). Call `list_elevenlabs_voices`, then pass `voice_id` as `elevenlabs_voice_id`. Leave `voice_type` and `voice_profile_id` empty. Free NarrateAI plans cannot connect it. ElevenLabs bills the speech.

**Saved cloned voice:** call `list_voices`, then pass that voice's `id` as `voice_profile_id` to `generate_tts`, `narrate_video_full`, `continue_to_full_video`, or `narrate_batch`. Leave `voice_type` empty. A new `voice_sample` overrides the saved voice.

**Voice cloning:** pass `voice_sample` (local path or URL) to `narrate_video_full`, `continue_to_full_video`, or `generate_tts`. It overrides `voice_type` and `voice_profile_id`. There is no model choice. English, Chinese, Japanese, Korean, German, French, Russian, Portuguese, Spanish, and Italian use the newer clone. English treats the sample as English. For the other nine, the sample language is detected and the narration is spoken in the selected language. Other narration languages use the multilingual clone. male2–male6 and female2–female5 use the newer clone for those same ten languages. male1 and female1 use the newer clone for the nine languages other than English, and Turbo for every language outside those ten. English male1 stays the regular fast voice and English female1 stays Turbo.

## Supported Languages

Narration and text-to-speech: en, es, fr, de, it, pt, ru, ja, ko, zh, ar, hi, nl, pl, sv, da, fi, no, tr, el, he, ms, sw.

## 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
