@paxalabs/mcp

Official MCP server for the Paxa Labs API: Thai, English, and Mandarin Chinese speech AI for your agent, including local audio playback, plus transcription, translation, and document reading across languages.

An agent connected to this server can speak out loud through your machine's speakers, read long content aloud as a managed playback queue, save speech to audio files, listen for a spoken reply, transcribe recordings with subtitles, translate between 15 languages, read PDFs and images with OCR, and extract typed fields from documents.

Beta. The tool set is complete and tested end to end, but tool names and behavior may still change before 1.0 as feedback comes in. Report problems at https://github.com/paxalabs/mcp/issues.

Quick start

Add the server, then ask your agent to sign in to Paxa: your browser opens the Paxa sign-in page, and you approve there. New accounts include free credits. See Sign in for the details, or for using an API key instead.

Claude Code

claude mcp add paxa -- npx -y @paxalabs/mcp

Claude Desktop, Cursor, and other MCP clients

Add to your client's MCP configuration (for Claude Desktop: claude_desktop_config.json):

{
  "mcpServers": {
    "paxa": {
      "command": "npx",
      "args": ["-y", "@paxalabs/mcp"]
    }
  }
}

One click for Cursor or VS Code: the buttons install the same entry into ~/.cursor/mcp.json or VS Code's MCP settings.

Sign in

Ask your agent to sign in to Paxa (the sign_in tool), or run npx -y @paxalabs/mcp login in a terminal. Your browser opens the Paxa sign-in page with a code filled in, and you approve there. The sign-in is kept in your user config folder (~/Library/Application Support/paxa/auth.json on macOS, ~/.config/paxa/auth.json on Linux, %APPDATA%\paxa\auth.json on Windows), readable only by you, and every Paxa server and paxa say on the machine use it. It renews itself, and lasts until you sign out or leave it unused for 30 days.

The connection is listed under API keys at paxalabs.com/app/keys, where you can give it a credit limit or disconnect it. npx -y @paxalabs/mcp logout signs this machine out.

To use an API key instead, create one there and set PAXA_API_KEY in the server's configuration, for Claude Code:

claude mcp add paxa -e PAXA_API_KEY=pxa_your_key_here -- npx -y @paxalabs/mcp

A key, when set, is used instead of the sign-in. Keys suit CI, machines without a browser, and a separate spending cap per project.

Tools

All audio flows through one ordered queue, so sounds never overlap: speak lines slip in ahead of queued long-form segments, and queue_speech keeps a book or article flowing gap-free by synthesizing the next segment while the current one plays.

With a streaming-capable player installed (see below), speech starts on the first bytes from the API instead of after the full download: about 0.3 s to the first word regardless of length, versus 0.7 s for a short line and 2.5 s for a long paragraph when buffered.

Voice mode for Claude Code

Three pieces turn Claude Code into something you can walk away from: it talks when it has news, and it calls you when it needs you.

1. Install the server (Quick start above).

2. Tell Claude when to talk. Add this to ~/.claude/CLAUDE.md, or to one project's CLAUDE.md:

## Voice

I have the Paxa MCP server (tools: speak, queue_speech, control_playback).
I am often away from the screen, so use voice like this:

- At the end of a turn where you did real work, call speak with a one or
  two sentence summary before writing the final message: what you did,
  what is next, and anything you need from me.
- When you need a decision from me, speak the question too.
- Keep it short and conversational. Never read code, file paths, logs, or
  long lists aloud. Those stay in text.
- Do not speak for quick back-and-forth or trivial answers.
- If I ask to hear something long, use queue_speech.
- Speak in the language I write in.

3. Get told when Claude needs you. When Claude Code waits for a permission or an answer, the model is not running, so it cannot call speak. Claude Code fires a hook at those moments instead, and paxa say turns the hook into a spoken phrase such as "Permission needed." Put the paxa command on your PATH:

npm install -g @paxalabs/mcp

Then add to ~/.claude/settings.json:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt|idle_prompt|agent_needs_input",
        "hooks": [{ "type": "command", "command": "paxa say" }]
      }
    ]
  }
}

paxa say takes the key from PAXA_API_KEY, or from the paxa entry in ~/.claude.json when that is unset, or else uses the sign-in on this machine, so step 1 is all the setup it needs. A Stop hook configured the same way speaks "Done." at the end of every turn.

The built-in phrases are synthesized once per voice and kept in your user cache directory (~/Library/Caches/paxa/say on macOS, ~/.cache/paxa/say on Linux, %LOCALAPPDATA%\paxa\cache\say on Windows). After that first play, which costs well under one credit, a notification plays from disk: no network round trip and no credits.

To change the words, write your own text in the hook command and add --cache so it gets the same treatment. One entry per event, since the matcher picks the event:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [{ "type": "command", "command": "paxa say --cache \"Hey, need your OK\"" }]
      },
      {
        "matcher": "idle_prompt|agent_needs_input",
        "hooks": [{ "type": "command", "command": "paxa say --cache --voice cookie \"Your turn\"" }]
      }
    ]
  }
}

Without --cache, nothing you type or pipe into paxa say is written to disk, and messages carried inside a hook payload never are.

On macOS the built-in afplay needs about half a second just to start and stop, which is most of the delay you hear on a short phrase. With brew install mpg123 (or ffmpeg) installed, cached phrases play through that instead: mpg123 starts in about 50 ms, ffplay in about 300 ms.

paxa say also works on its own:

paxa say "Build finished"
paxa say --voice cookie "Deploy is live"

If your editor or desktop app was not launched from a terminal, its PATH may not include your node bin directory, and the hook will fail silently. Use the absolute path to paxa in the hook command if that happens.

Speech models

Speech runs on Paxa TTS Flash v2 by default: 50 voices that each speak Thai, English, and Mandarin Chinese, and every voice reads direction tags written into the text, such as [whispering], [laughs], [speaking slowly, close to the microphone], a weighted blend like [happy:0.7+sad:0.3], or <emph> and <whisper> marks. Pause tags add silence where they stand: [short pause], [pause], [long pause], or an exact [pause 300ms] up to 500 ms. Nothing in brackets is spoken, tag characters bill as text, and a tag the model cannot do is refused before any charge. The directions guide lists every sound and rule.

temperature (0 to 2, default 0.5) sets how much a reading varies from one request to the next. Use 0 when a line must match the takes around it, such as one sentence regenerated inside a finished voiceover.

Pass model: "paxa-tts-flash-v1" on a call, or set PAXA_TTS_MODEL, only for v1's legacy features: four Thai voices with regional accents (Isan, Northern, Southern), the fixed emotion tags on khanomchan and kaprao, or one of the eight voices v2 does not carry (donut, toast, padthai, yoyo, somtam, larb, khaosoi, roti). Same price and limits on both.

Design your own voice

When no catalog voice fits, describe the one you want. design_voice turns one or two sentences (who is speaking, how they sound, where it will be heard, and the language they speak) into a voice and plays the line it speaks. refine_voice takes one change at a time, such as "a little lower and slower", and the rest of the voice stays; earlier drafts stay usable, so you can go back to one. save_voice keeps the draft you like under an id (voice_...) that speak, queue_speech, and text_to_speech accept on Paxa TTS Flash v2; set it as PAXA_DEFAULT_VOICE to make it the default. Each design or change costs 5 credits, saving is free, and speech in a designed voice costs 1.25x. Your plan sets how many voices you keep (Free 1, Starter 3, Standard 10, Pro 50); list_voices shows them with the slots in use, rename_voice renames one, and delete_voice frees one. The voice description guide has examples.

Content creation

Four things creators asked for, each the local half of an API call:

• Transcribe a video. Give transcribe_audio an mp4, mov, mkv, or most other containers; ffmpeg pulls the sound track out locally and the API transcribes it. Add pauses_over: 0.7 and the result lists every silence longer than that with its start and end, the dead air to cut. Ask for save: ["srt"] and the captions come back too.
• Voiceover with captions that match. text_to_speech with subtitles: "srt" (or "vtt") writes a caption file next to the audio, timed from the synthesized words. Cues break at sentence punctuation, at pauses, and at the line budget, never inside a word, and Thai lines end where the writer put a space. A Chinese character takes two columns of the line budget, so Mandarin lines hold 16 characters by default. Timed synthesis bills 1.25x.
• Long narration to one file. Scripts past 20,000 characters are split at paragraphs and sentences, synthesized part by part, and joined into a single file, captions offset to match.
• Conversations in several voices. dialogue_to_speech takes the lines in speaking order, each with its voice, and writes one file with gap_ms of silence between lines (300 by default). The result lists where each line starts and ends, and caption cues never cross from one line to the next. Scripts past 100 lines or 20,000 characters are sent in parts and joined with the same gap. If a request fails partway, the lines that arrived whole are kept and the result names the line to resume from.

ffmpeg is the one requirement for video input and for joining mp3, opus, or wav parts (brew install ffmpeg on macOS). Raw pcm, mulaw, and alaw parts join without it, and everything else works without it too.

Translation

translate writes any of 15 languages from any other: Thai, English, Chinese (Simplified), Japanese, Korean, Arabic, French, German, Hindi, Indonesian, Malay, Portuguese, Russian, Spanish, and Vietnamese. target is required; the source is detected per segment, so mixed-language text works, and source pins it when detection is wrong. Formality, borrowed words, glossaries, and style examples follow the target, and alternatives (up to 5) sets how many renderings come back in total, the best first, each billed as another pass over the text. Send a whole glossary: terms that do not appear in the text are dropped before billing, and the result says how many were sent.

Listening

listen turns the microphone into an answer. Ask a question with speak, call listen, and the user's spoken reply comes back as text as soon as they stop talking: Paxa's realtime transcription detects the end of the turn, so nothing has to guess at silence. The audio goes straight to the API and is never written to disk. A few seconds of listening costs well under one credit (12.5 credits per minute, silence included).

It needs a command-line recorder, which stock macOS and Windows do not ship: brew install ffmpeg or brew install sox on macOS; sox on Windows (or ffmpeg with PAXA_MIC set to the DirectShow device name); ffmpeg, sox, parecord, or arecord on Linux. It also needs Node 22 or newer, and the app that launched the server (Terminal, VS Code, Claude Desktop) must have microphone permission. PAXA_MIC picks a device when the system default is not the one you want. To check recognition without a microphone, node scripts/listen-file.mjs recording.mp3 feeds a file through the same session.

Environment variables

To pin a different list per project, set the vocabulary variables in a project-scope server entry (Claude Code's project scope, .cursor/mcp.json, .vscode/mcp.json). On each call the tool takes the call's own terms first, then the configured ones, deduplicated and cut at the API's limit of 50, and reports how many it pinned.

Playback support

Streaming needs a player that reads from stdin. On macOS, brew install mpg123 (the quickest to start) or ffmpeg enables it; without one, speech still plays through afplay after the download completes. If no player is found at all, speech tools report it clearly and text_to_speech still works.

Claude Desktop extension

Each release on GitHub ships a .mcpb bundle. Download it, open it with Claude Desktop, and ask Claude to sign in to Paxa (or enter an API key in the extension settings). The bundle carries its own copy of the server and its dependencies, so it works without Node.js or npm on the machine.

Development

pnpm install
pnpm build        # compile to dist/
pnpm typecheck
pnpm mcpb         # build release/paxalabs-mcp-<version>.mcpb for Claude Desktop

# live smoke test (spends a few credits, plays audio out loud)
PAXA_API_KEY=pxa_... TEST_OUT_DIR=/tmp/paxa-out node scripts/e2e.mjs