narrador

narrador MCP server

narrador turns documents and X (Twitter) posts into natural narrated audio with word-level timestamps. Upload PDFs, Word, EPUBs or text, pick a voice (or let narrador files choose one from the document language), start conversion jobs, check status and download audio with synced timings. narrador X turns posts into audio the same way. Sign in with OAuth at narrador.io, or use a product API key.

Remote Model Context Protocol server for narrador. It lets AI agents (Claude, Cursor, VS Code, Windsurf, ChatGPT and any MCP client) use narrador files and narrador X.

• narrador files: PDF, Word, EPUB and other documents → audio with word-level timings.
• narrador X: X/Twitter posts → audio.

Endpoint	https://api.narrador.io/mcp (Streamable HTTP)
Auth	OAuth 2.1 (recommended) or API key
REST API docs	https://api.narrador.io/docs
OpenAPI	https://api.narrador.io/openapi.json
Website	https://narrador.io

Repository: https://github.com/narrador-io/narrador-mcp

This repository only holds the public listing (server.json), registry metadata (glama.json) and documentation. The server is hosted by narrador; there is nothing to install locally.

Credits

Usage is metered in narrador credits (see get_account). Jobs and generations consume credits when they run. There are no subscriptions—buy credits in the narrador web app and check balance before calling tools that spend credits.

Tools (7)

Tool	Product	What it does
get_account	both	Identity, product scope, and narrador credit balances (read-only)
list_voices	both	Voices for narrador files or narrador X
create_files_job	narrador files	Start a document → audio job
get_files_job	narrador files	Poll job status and progress
get_files_result	narrador files	Download audio and word timings for a completed job
generate_x_audio	narrador X	Generate audio for an X post
get_x_generation	narrador X	Fetch a generation you created earlier

get_account

No parameters. Returns user, app (API key product or null for OAuth), products (files and/or x), and credits (totalAvailable and per-bucket balances). Does not consume credits.

list_voices

Parameter	Required	Description
product	No	files or x—which catalog to list. Defaults to the API key’s product, or files when an OAuth token has both products.

Each voice includes id, name, tier (standard or cheaper), defaultAccent, isPublic, description, and sampleUrl (https://api.narrador.io/v1/voices/{id}/sample, a neutral sample redirect that does not require an API key). A legacy provider field may mirror tier and is deprecated—use tier.

create_files_job

Provide either text or fileId, not both.

Parameter	Required	Description
text	One of text/fileId	Plain text (1–500,000 characters). fileName optional (defaults to document.txt).
fileId	One of text/fileId	UUID of an uploaded file. fileName required.
fileName	If fileId	Job file name (1–200 characters).
voiceId	No	Voice UUID from list_voices. Must be set together with accent, or omit both.
accent	No	Accent code (e.g. en-us, es-es, pt-br). Must be set together with voiceId, or omit both.

When voiceId and accent are omitted, narrador detects language from the document (en-us, es-es, pt-br). Very short or undetectable text falls back to en-us. It then picks a standard tier voice for that language, or a cheaper tier voice if none—deterministic catalog order. If the detected language has no supported voice, the job ends with failed_file_processing; pass voiceId and accent explicitly.

Returns jobId. Poll with get_files_job, then call get_files_result when status is completed. Consumes credits.

get_files_job

Parameter	Required	Description
jobId	Yes	UUID from create_files_job.

Returns status (e.g. processing, completed, failed), progressPercentage, and audioId when ready.

get_files_result

Parameter	Required	Description
jobId	Yes	Completed job UUID.

Returns audioUrl, audioId, duration, and wordTimings (word, startTime, endTime).

generate_x_audio

Parameter	Required	Description
voiceId	Yes	Voice UUID from list_voices (product: x).
accent	No	Accent code; defaults to en-us.
postId	One of postId/postUrl	Numeric X post id.
postUrl	One of postId/postUrl	Full X post URL.

Returns generationId, audioUrl, duration, and wordTimings when ready (often immediately). Poll get_x_generation if needed. Consumes credits.

get_x_generation

Parameter	Required	Description
generationId	Yes	UUID from generate_x_audio.

Returns the same audio metadata as a successful generate_x_audio call. Only generations linked to your account are returned; other ids respond with generation not found.

Authentication

OAuth (recommended). Add the URL https://api.narrador.io/mcp to your client. The client discovers the authorization server (https://narrador.io/api/auth); sign in on narrador.io and approve access. Scopes: narrador:files, narrador:x.

API key. Create a key in the narrador web app and send it as Authorization: Bearer <key> or x-api-key: <key>. Keys are scoped per product:

Product	Prefix
narrador files	nrd_files_
narrador X	nrd_x_

Connect

Claude Desktop

Settings → Connectors → Add custom connector → URL https://api.narrador.io/mcp → Connect, then complete OAuth on narrador.io.

Cursor

Project (.cursor/mcp.json) or user (~/.cursor/mcp.json):

{
  "mcpServers": {
    "narrador": { "url": "https://api.narrador.io/mcp" }
  }
}

With an API key:

{
  "mcpServers": {
    "narrador": {
      "url": "https://api.narrador.io/mcp",
      "headers": { "Authorization": "Bearer nrd_files_..." }
    }
  }
}

VS Code

.vscode/mcp.json:

{
  "servers": {
    "narrador": { "type": "http", "url": "https://api.narrador.io/mcp" }
  }
}

Claude (claude.ai)

Same as Claude Desktop: Add custom connector with https://api.narrador.io/mcp.

Claude Code

claude mcp add --transport http narrador https://api.narrador.io/mcp

Windsurf (~/.codeium/windsurf/mcp_config.json)

{
  "mcpServers": {
    "narrador": { "serverUrl": "https://api.narrador.io/mcp" }
  }
}

Any other client

Point it at https://api.narrador.io/mcp (Streamable HTTP). If the client has no OAuth support, send an API key in the Authorization header.

Example prompts

• "Check my narrador credits, then convert this PDF to audio with narrador files."
• "List standard-tier voices for narrador files in Spanish, then create a job for this text."
• "Turn this X post into audio with narrador X: https://x.com/…/status/…"

License

MIT. See LICENSE.