narrateai-mcp 0.4.3

MCP server for NarrateAI - get timed transcript from silent video

NarrateAI MCP Server

MCP server that exposes NarrateAI's video-to-transcript flow as a tool. Upload a silent video (via URL), run frame analysis + workflow understanding + transcription, and get back a timed transcript with segments.

No changes to the main app. This is a standalone MCP server that calls your existing NarrateAI API.

Prerequisites

1. NarrateAI app running — Backend (FastAPI) must be running, e.g. uv run python main.py or your production URL.
2. API key — Create one in the NarrateAI web app (Settings → API Keys).
3. Video URL — A public URL to an MP4 (e.g. S3 signed URL, GitHub raw, etc.).

Install

From the project root:

cd mcp-server
uv sync

Run locally (stdio)

cd mcp-server
NARRATEAI_API_KEY=your_key_here NARRATEAI_API_BASE_URL=http://localhost:8000 uv run python -m narrateai_mcp

Stdin/stdout are used for MCP protocol, so you won't see interactive output. Use this via Cursor or another MCP client.

Cursor setup

1. Add your API key to .cursor/mcp.json (replace the empty NARRATEAI_API_KEY; avoid committing real keys):

   {
     "mcpServers": {
       "narrateai": {
         "command": "uv",
         "args": ["run", "-C", "mcp-server", "python", "-m", "narrateai_mcp"],
         "env": {
           "NARRATEAI_API_BASE_URL": "http://localhost:8000",
           "NARRATEAI_API_KEY": "demo_sk_live_xxxx"
         }
       }
     }
   }
   

2. If your app runs elsewhere, set NARRATEAI_API_BASE_URL to that URL (e.g. https://api.narrateai.app).

3. Restart Cursor completely (quit and reopen).

4. In Cursor, the tools will appear. You can ask, e.g.:

   • "Use the narrate_video_transcript tool with this video URL: https://example.com/demo.mp4"
   • "Transcribe this video (it's in Spanish): https://example.com/podcast.mp4"

Tool: transcribe_video

Transcription only: video with existing voice → speech-to-text → timed transcript. No translation.

Argument	Type	Description
video_source	string	Public URL or local file path of the video.
source_language	string	REQUIRED. Language of the speech (en, es, fr, zh, etc.). Ask user if not specified.
api_key	string	(Optional) API key. Defaults to NARRATEAI_API_KEY env var.

Returns: JSON with job_id. Poll get_job_result(job_id) until status is transcript_ready.

Tool: translate_video

Translation (new upload): video with voice → transcribe → translate → translated transcript.

Argument	Type	Description
video_source	string	Public URL or local file path.
source_language	string	REQUIRED. Language of the speech.
target_language	string	REQUIRED. Language to translate to.
api_key	string	(Optional) API key.

Returns: JSON with job_id. Poll get_job_result(job_id) until transcript_ready.

Tool: translate_existing_video

Translation (existing video): Translate transcript of a video already in the user's library. Sync – returns immediately.

Argument	Type	Description
job_id	string	Job ID of the completed video (from user's library).
source_language	string	REQUIRED. Language of the current transcript.
target_language	string	REQUIRED. Language to translate to.
api_key	string	(Optional) API key.

Returns: JSON with transcript, total_duration, total_words.

Tool: dub_video_full

Full auto-dubbing: transcribe → translate → extract speaker voice → TTS with cloned voice → dubbed video. No refinement screen.

Argument	Type	Description
video_source	string	Public URL or local file path.
source_language	string	REQUIRED. Language of the speech.
target_language	string	REQUIRED. Language to dub into.
preserve_background_music	boolean	REQUIRED. Ask user: keep background music (true) or not (false).
api_key	string	(Optional) API key.

Returns: JSON with job_id. Poll get_job_result(job_id) until status is completed, then video_url has the dubbed video.

Tool: narrate_video_transcript

Argument	Type	Description
video_url	string	Public URL of the video (MP4).
api_key	string	(Optional) API key. Defaults to NARRATEAI_API_KEY env var.
language	string	Language code (en, es, fr, de, etc.). Default: en.
max_wait_seconds	float	Max time to wait for transcript. Default: 600.

Returns: JSON with transcript (timed segments), workflow_understanding, visual_timeline, total_duration, total_words.

Output format (transcript segments)

Each segment has:

• start_time, end_time (seconds)
• text — narration for that segment
• duration, pause_duration, chunk_type, segment_id

Troubleshooting

• "API key required" — Set NARRATEAI_API_KEY in env or pass api_key to the tool.
• "Temporary redirect service not available" — Backend must have USE_TEMP_REDIRECTS and GCS configured.
• "Transcript not ready" / timeout — Video may be long or processing slow. Try a shorter clip or raise max_wait_seconds.
• 429 / rate limit — Check your subscription tier and daily API limits in NarrateAI.