Skip to main content
Glama
Tapra MCP server
by tapra-ai

Tapra MCP server

npm CI License: MIT

Setup guide for every app: tapra.tn/mcp · API reference: tapra.tn/docs

Use Tapra from Claude Desktop, Claude Code, Cursor, or any MCP client: transcribe Tunisian Derja mixed with French and English, subtitle videos, generate speech and voiceovers, and convert between Arabizi and Arabic script.

The server runs locally over stdio. It reads your media files, calls the Tapra API with your key, and writes results to your output folder. Calls are billed like the API, and every paid tool reports its cost and your remaining balance.

Setup

  1. Create an API key at https://tapra.tn/dashboard.

  2. Install ffmpeg (needed for video, long-file chunking and cost estimates on audio): winget install Gyan.FFmpeg, brew install ffmpeg, or apt install ffmpeg.

  3. Add the server to your client.

Claude Desktop / Cursor (claude_desktop_config.json or .cursor/mcp.json):

{
  "mcpServers": {
    "tapra": {
      "command": "npx",
      "args": ["-y", "@tapra/mcp"],
      "env": {
        "TAPRA_API_KEY": "tapra_sk_live_…",
        "TAPRA_OUTPUT_DIR": "~/Tapra"
      }
    }
  }
}

Claude Code:

claude mcp add tapra -e TAPRA_API_KEY=tapra_sk_live_… -- npx -y @tapra/mcp

Related MCP server: video-summarizer

Tools

Tool

What it does

Billed

tapra_status

API health, models, prices, balance, output folder, ffmpeg check

free

get_balance

Balance, total spent, and the 10 latest charges for your key

free

list_voices

The Tapra voices and what each sounds like

free

speech_to_text

Transcribe audio or video: one folder with txt, srt and vtt (+ json), speakers detected and colored, a clip of each voice and a speakers.html report

per minute

transcribe_video

Subtitles for a video (srt + vtt + txt in one call), readable cue lengths, speaker colors, optional burned-in MP4

per minute

name_speakers

Name the detected speakers (and pick colors); rewrites txt/srt/vtt, merges labels given the same name, can burn the result

free

diarize_audio

Who spoke when, without a transcript

per minute

text_to_speech

Speak Derja / Arabizi / French / English with a Tapra voice, effect tags, 19 formats

per character

create_voiceover

Narration from a script, or dubbing from an SRT, on one timeline; writes the track, per-line clips and manifest.json; can lay it onto a video

per character

play_audio

Play a file on this computer's speakers (or stop playback)

free

find_in_transcript

When is a word or phrase said? Word-level times from a JSON transcript

free

edit_audio

Join, trim, remove silences, normalize loudness, fade, convert

free

convert_script

Arabizi ↔ Arabic script

per character

Example prompts:

  • "Subtitle ~/Videos/interview.mp4 with speaker labels and burn them in."

  • "Write a 30-second Derja ad for a coffee shop, then make a voiceover with a warm female voice."

  • "Narrate this script with Zeineb, then lay it onto ~/Videos/promo.mp4."

  • "Where does she say 'el budget' in interview.json? Cut 5 seconds around it and normalize to -14 LUFS."

Voices

Voice

Sounds like

youssef

Man. The default.

zeineb

Woman. A warm storyteller, made for narration.

karim

Man. Calm.

sarra

Woman. Clear.

anis

Man. Clear.

rim

Woman.

hamza

Man.

mariem

Woman.

mehdi

Man.

ines

Woman.

walid

Man.

Speech is always pronounced the Tunisian way (loanwords and Arabizi). Effect tags go inline and are not billed: [euh] hesitation, [aaa] long filler, [hmm], [ahem] throat clear, [ouf] sigh, [breath] out-breath, [stutter] (right before the word to stutter), e.g. "[euh] ma na3rafch, [breath] khalli nchouf". Unknown tags are refused before any charge.

list_voices reads the current list from the API (GET /v1/voices), so voices added on the server work without updating the MCP; the table above is the built-in copy used when the API cannot be reached. quality: "flash" uses the same voices about 5x faster and cheaper. Voice cloning is not currently available; the server tells the model so, and it should offer these voices instead.

Audio formats

format on text_to_speech, create_voiceover and edit_audio: wav (default, lossless) or one of the 18 ElevenLabs-style formats: mp3_22050_32, mp3_44100_32/64/96/128/192, pcm_8000/16000/22050/24000/44100 (16-bit WAV at that rate), ulaw_8000 / alaw_8000 (G.711 telephony, in WAV), opus_48000_32/64/96/128/192 (Ogg Opus). pcm needs nothing extra; mp3, opus, ulaw and alaw need ffmpeg.

Progress

speech_to_text, transcribe_video, create_voiceover and edit_audio send MCP progress notifications (per chunk, line or batch) when the client asks for them, so long jobs show progress and do not time out.

Voiceover manifest

create_voiceover writes a folder you can hand to a video tool:

voiceover_20261027-142233-a1b2/
  voiceover.wav      full narration
  manifest.json      { duration, segments: [{ index, text, start, end, clip }] }
  clips/001.wav …    one clip per line

With srt_path, timing: "fit" asks the model to make each line last as long as its subtitle, which is what dubbing needs. timing: "natural" keeps natural pacing and warns when a line spills into the next one.

Configuration

Variable

Default

Meaning

TAPRA_API_KEY

required

Your tapra_sk_live_… key

TAPRA_API_URL

read from tapra.tn

Force an API origin. Must be https://; plain http:// only for localhost / 127.0.0.1 (e.g. http://127.0.0.1:8787 for a local model host). A non-tapra.tn host gets a warning on stderr, since your key is sent there

TAPRA_SITE_URL

https://www.tapra.tn

Website serving the price list, balance, and the current API address

TAPRA_OUTPUT_DIR

~/Tapra

Where generated files go; outputs can't be written anywhere else

TAPRA_BASE_PATH

home folder

Input files must be inside this folder; relative paths resolve here. Hidden folders/files (.ssh, .config, …) at any depth, and AppData / Library directly inside it, are never read

TAPRA_MCP_OUTPUT_MODE

files

files saves results; resources returns them inline only (nothing saved); both does both

TAPRA_MCP_MAX_INLINE_MB

15

Largest file returned inline in resources / both mode

TAPRA_MAX_COST_TND

20

Refuse any single call estimated above this many TND. Only you can raise it; a tool's max_cost_tnd argument can only lower it

TAPRA_ALLOW_UNESTIMATED

off

1 lets paid calls run when no cost estimate is possible (price list unreachable, or no ffmpeg to measure audio). Off: such calls are refused

TAPRA_FFMPEG_PATH

ffmpeg

Path to ffmpeg if it is not on PATH

TAPRA_TIMEOUT_SECONDS

600

Per-request timeout

TAPRA_AUDIO_PLAYER

ffplay, then the system player

Program play_audio runs as <player> <file>. A Windows .cmd/.bat player runs through the shell, so file names containing % ! ^ & | < > " are refused with it; prefer an .exe

Without TAPRA_API_URL, the server asks TAPRA_SITE_URL/api/openapi for the current API address, so moving the model host needs no client change. Only an https:// address on tapra.tn or a subdomain is accepted (your key is sent there); anything else falls back to https://api.tapra.tn.

Spending: every paid call is estimated first and refused above TAPRA_MAX_COST_TND (20 TND per call when unset, about 2 h of transcription). The model can pass max_cost_tnd to ask for a lower cap, never a higher one. Audio length is measured on the extracted audio, not the file header, and extraction stops at the length the cap pays for. When no estimate is possible (price list unreachable, or ffmpeg missing so the length is unknown) the call is refused unless TAPRA_ALLOW_UNESTIMATED=1.

File safety: inputs outside TAPRA_BASE_PATH (including through symlinks) and outputs outside TAPRA_OUTPUT_DIR (including through symlinks or junctions) are refused. Tools that work on results, like play_audio and edit_audio, also accept files in the output folder or tapra://output/... URIs. Inside the base folder, hidden folders and files (any path part starting with ., such as .ssh or .aws) and AppData / Library directly under it are refused too, checked on the real path and ignoring case. An existing file is never replaced (take.wav becomes take-1.wav). A missing input gets "did you mean" suggestions from the same folder. Every file a tool makes can be re-read as an MCP resource, tapra://output/<path>.

Every paid call sends a fresh Idempotency-Key, so automatic retries are never charged twice. Files longer than 15 minutes are split into chunks; with speaker labels on, labels restart in each chunk (prefixed c1-, c2-, …).

Development

npm install
npm test        # builds, then runs the unit, path-safety and end-to-end tests against a mock API
npx @modelcontextprotocol/inspector node dist/index.js

Tests need Node.js 22+ and ffmpeg (video and long-file tests are skipped without it). They never call the real Tapra API.

Issues and pull requests are welcome. For questions about your account or billing, write to contact@tapra.tn.

License

MIT. The server is open source; the Tapra models it calls are a paid API.

Available Tools

16 tools
convert_scriptArabizi ↔ ArabicA

Convert Tunisian text between Arabizi (Latin letters and digits, e.g. "3aslema, chna7welek?") and Arabic script, in either direction. Costs money per character.

Inputs: text (required), direction (required), max_cost_tnd.

create_voiceoverCreate a voiceoverA

Turn a script or a subtitle file into one narration track for video work. Each line is spoken with the same Tapra voice (amal = Mature woman. Warm, grounded, everyday Tunisian.; salma = Younger woman. Lighter and brighter, conversational.; salah = Man with a big, sharp (aigu) voice that carries. Strong presence.; fahmi = Middle-aged man. Normal, natural male voice.; leo = Young man. Light and energetic. The default Tapra voice.; voice cloning is not available) and placed on a timeline: at its subtitle time (from srt_path) or one after another (from script or lines). Lines may use effect tags ([euh] breathy hesitation; [aaa] long filler while thinking; [hmm] closed-mouth "mmm"; [ahem] clears the throat; [ouf] tired sigh; [breath] out-breath, "haah"; [stutter] repeats the first sound of the next word; put it right before that word). Writes a folder with the voiceover track (wav or another format), one WAV clip per line, and manifest.json (text + start/end per clip) that video generation tools can follow. Optionally lays the voiceover onto a video. Reports progress per line. Costs money per character.

Inputs: lines, speed, voice, format, +10 more.

diarize_audioWho spoke whenA

Find speaker turns in an audio or video file (no transcript). Returns each turn with its speaker and times. Costs money per minute.

Inputs: input_path (required), output_path, max_cost_tnd.

edit_audioEdit audioA

Prepare audio for videos and posts, locally with ffmpeg: join several files in order, trim, remove long silences, normalize loudness (-14 LUFS for social video, -16 podcasts, -23 broadcast), fade in/out, and convert to any of the 19 formats. Video inputs contribute their sound. Writes a new file; never changes the originals. Free.

Inputs: input_paths (required), format, channels, trim_end, +8 more.

find_in_transcriptFind in transcriptA
Read-onlyIdempotent

Find when a word or phrase is said, with timestamps, in a transcript saved by speech_to_text or transcribe_video (.json gives word-level times; .srt/.vtt give subtitle-level times). Matches Arabic script with or without harakat and letter variants (أ/ا, ة/ه, ى/ي), French accents optional, and small typos when fuzzy. Useful for cutting video ("where does he say X?"). Free, runs locally.

Inputs: query (required), transcript_path (required), fuzzy, max_results.

get_balanceBalance and usageA
Read-onlyIdempotent

Show the Tapra balance (TND), total spent, and the 10 most recent charges for this API key. Free.

Inputs: no named parameters.

list_translation_languagesTranslation languagesA
Read-onlyIdempotent

List the languages translate accepts as source and target. Free.

Inputs: no named parameters.

list_voicesTapra voicesA
Read-onlyIdempotent

List the Tapra voices for text_to_speech and create_voiceover, with a description of each. Free. Also answers questions about voice cloning, which is not currently available.

Inputs: no named parameters.

name_speakersName speakersA

Give the speakers found by speech_to_text or transcribe_video real names (and optionally colors), then rewrite the txt, srt and vtt with those names. Each speaker keeps one subtitle color (srt colors, vtt voice styles). Labels given the same name are merged into one speaker. Free, works offline. Can also burn the named subtitles into the video.

Inputs: names (required), transcript_path (required), colors, formats, +2 more.

play_audioPlay audioA
Read-onlyIdempotent

Play an audio or video file on this computer's speakers (for example a clip you just generated). Returns right away while it plays; a new play stops the previous one. Set stop to just stop playback. Free.

Inputs: stop, input_path.

speech_to_textTranscribe audioA

Transcribe an audio or video file with Tapra, which handles Tunisian Derja mixed with French and English. One call writes a folder with the transcript as txt, srt and vtt (plus a .json with full timings). Speakers are labelled by default (no extra charge): the result says how many were detected, with talk time, a quote and an audio clip of each, and a speakers.html page. When there are several speakers, ask the user whether to name them, then call name_speakers. Long files are split into chunks automatically. Costs money per minute of audio.

Inputs: input_path (required), prompt, diarize, formats, +4 more.

tapra_statusTapra statusA
Read-onlyIdempotent

Check the Tapra connection: API health, available models, current prices, output folder, and whether ffmpeg is installed. Free. Call this first when a tool fails.

Inputs: no named parameters.

text_to_speechText to speechA

Speak text in Tunisian Derja (Arabic script or Arabizi), French, English, or a mix with one of the Tapra voices, with Tunisian pronunciation. Voices: amal = Mature woman. Warm, grounded, everyday Tunisian.; salma = Younger woman. Lighter and brighter, conversational.; salah = Man with a big, sharp (aigu) voice that carries. Strong presence.; fahmi = Middle-aged man. Normal, natural male voice.; leo = Young man. Light and energetic. The default Tapra voice.. Add non-verbal effects inline with tags (not billed): [euh] breathy hesitation; [aaa] long filler while thinking; [hmm] closed-mouth "mmm"; [ahem] clears the throat; [ouf] tired sigh; [breath] out-breath, "haah"; [stutter] repeats the first sound of the next word; put it right before that word. Example: "[euh] ma na3rafch, [breath] khalli nchouf". Saves the audio in the chosen format (wav by default, 18 other formats). Voice cloning and custom voice design are not currently available: if the user asks to clone a voice, say so and offer these voices. Costs money per character. For long scripts or narration timed to a video, use create_voiceover.

Inputs: text (required), speed, voice, format, +5 more.

transcribe_videoTranscribe video to subtitlesA

Make subtitles for a video: extracts the audio, transcribes Derja/French/English, and writes srt, vtt and txt in one go, timed for reading. Speakers are labelled and colored by default (no extra charge), with a speaker report and a clip of each voice; when there are several, ask the user whether to name them, then call name_speakers. Set burn_subtitles to also render a copy of the video with the subtitles drawn in. Needs ffmpeg. Costs money per minute.

Inputs: input_path (required), prompt, diarize, formats, +6 more.

translateTranslateA

Translate between Tunisian Derja and English, French, or Modern Standard Arabic (in both directions). Call list_translation_languages for the exact target names. Costs money per character.

Inputs: text (required), target (required), source, max_cost_tnd.

translate_subtitlesTranslate subtitlesA

Translate an SRT or VTT file between Tunisian Derja and English, French, or MSA, keeping every timing and speaker label. Lines are sent in batches to keep cost low. Pair with create_voiceover (srt_path) to dub a video. Reports progress per batch. Costs money per character.

Inputs: target (required), input_path (required), format, source, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 16 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes, and the descriptions explicitly disambiguate tricky pairs (translate vs translate_subtitles, text_to_speech vs create_voiceover). The main overlap is speech_to_text vs transcribe_video (which also accepts video input and transcribes it) and diarize_audio, since speech_to_text already labels speakers — an agent could hesitate over which to call for a video file.

    Naming Consistency4/5

    Everything is snake_case and mostly verb_noun (list_voices, get_balance, create_voiceover, edit_audio, find_in_transcript). A few deviate into noun-ish or product-prefixed forms (speech_to_text, text_to_speech, tapra_status), but the set stays predictable and scannable.

    Tool Count4/5

    16 tools is slightly above the ideal band but justified by the breadth of the domain (transcription, diarization, TTS, voiceover, translation, audio editing, diagnostics). No tool looks like pure filler, though diarize_audio comes closest since speech_to_text already returns speaker labels.

    Completeness4/5

    The surface covers a full media-localization lifecycle: status/balance, voice listing, STT, subtitles, speaker naming, diarization, TTS, voiceover, translation (text and subtitle files), script conversion, transcript search, playback, and ffmpeg editing. Minor gaps remain around discovering/managing previously generated output files or long-running jobs, which agents must work around by tracking paths themselves.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that converts videos, audio, and meeting recordings into structured transcripts and summaries with multi-backend ASR and automatic fallback.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Translate PDF, Word (DOCX), Excel (XLSX) and PowerPoint (PPTX) files, images, subtitles and text. Turn audio and video into transcripts or translated subtitles. Preserve layout where supported. Requires an Equalang API key and credits.
      8
      100 npm
      22
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      Enables MCP clients to use Arabic-centric AI for chat, cited Islamic Q&A, Qur'an and hadith quotation checks, deep research, Arabic-English translation, speech-to-text and text-to-speech, image generation, poetry, and safety moderation.
      12
      Apache 2.0