{
  "markdown": "# @paxalabs/mcp\n\n[![npm](https://img.shields.io/npm/v/@paxalabs/mcp)](https://www.npmjs.com/package/@paxalabs/mcp)\n[![CI](https://github.com/paxalabs/mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/paxalabs/mcp/actions/workflows/ci.yml)\n[![node](https://img.shields.io/node/v/@paxalabs/mcp)](https://nodejs.org)\n[![license](https://img.shields.io/npm/l/@paxalabs/mcp)](LICENSE)\n[![Claude Desktop bundle](https://img.shields.io/github/v/release/paxalabs/mcp?include_prereleases&label=Claude%20Desktop%20.mcpb)](https://github.com/paxalabs/mcp/releases)\n\n[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=paxa&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBwYXhhbGFicy9tY3AiXSwiZW52Ijp7IlBBWEFfQVBJX0tFWSI6InB4YV95b3VyX2tleV9oZXJlIn19)\n[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=paxa&config=%7B%22name%22%3A%22paxa%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40paxalabs/mcp%22%5D%2C%22env%22%3A%7B%22PAXA_API_KEY%22%3A%22pxa_your_key_here%22%7D%7D)\n\nOfficial [MCP](https://modelcontextprotocol.io) server for the\n[Paxa Labs API](https://paxalabs.com/docs): Thai and English speech AI for\nyour agent, including local audio playback.\n\nAn agent connected to this server can speak out loud through your machine's\nspeakers, read long content aloud as a managed playback queue, save speech to\naudio files, translate any language into Thai, and read PDFs and images with\nOCR.\n\n> **Beta.** The tool set is complete and tested end to end, but tool names and\n> behavior may still change before 1.0 as feedback comes in. Report problems at\n> https://github.com/paxalabs/mcp/issues.\n\n## Quick start\n\nYou need a Paxa API key from [paxalabs.com](https://paxalabs.com). New\naccounts include free credits.\n\n### Claude Code\n\n```bash\nclaude mcp add paxa -e PAXA_API_KEY=pxa_your_key_here -- npx -y @paxalabs/mcp\n```\n\n### Claude Desktop, Cursor, and other MCP clients\n\nAdd to your client's MCP configuration (for Claude Desktop:\n`claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"paxa\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@paxalabs/mcp\"],\n      \"env\": {\n        \"PAXA_API_KEY\": \"pxa_your_key_here\"\n      }\n    }\n  }\n}\n```\n\n**One click for Cursor or VS Code:** the buttons install the same entry\ninto `~/.cursor/mcp.json` or VS Code's MCP settings. Then replace\n`pxa_your_key_here` in the `paxa` entry with your key.\n\n[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=paxa&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBwYXhhbGFicy9tY3AiXSwiZW52Ijp7IlBBWEFfQVBJX0tFWSI6InB4YV95b3VyX2tleV9oZXJlIn19)\n[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=paxa&config=%7B%22name%22%3A%22paxa%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40paxalabs/mcp%22%5D%2C%22env%22%3A%7B%22PAXA_API_KEY%22%3A%22pxa_your_key_here%22%7D%7D)\n\n## Tools\n\n| Tool | What it does | Credits |\n| --- | --- | --- |\n| `speak` | Synthesize a short line and play it through the speakers, blocking until done | 15 per 1000 chars |\n| `queue_speech` | Read long content aloud: auto-chunks, synthesizes ahead while playing, returns immediately | 15 per 1000 chars |\n| `control_playback` | Control the shared audio queue: `status`, `pause`, `resume`, `skip`, `clear` | free |\n| `play_audio` | Play a local audio file through the speakers | free |\n| `text_to_speech` | Synthesize speech to an audio file (mp3, opus, wav) without playing it | 15 per 1000 chars |\n| `translate_to_thai` | Translate any language into Thai, with formality, glossary, and context controls | 25 per 1000 chars |\n| `ocr_document` | OCR a local PDF, PNG, JPEG, or WebP into Markdown or structured blocks | 6.5 per page |\n| `list_voices` | The TTS voice roster with character notes | free |\n| `list_models` | Available models, limits, and pricing | free |\n| `get_account` | Credit balance, plan, and rate limits | free |\n\nAll audio flows through one ordered queue, so sounds never overlap: `speak`\nlines slip in ahead of queued long-form segments, and `queue_speech` keeps a\nbook or article flowing gap-free by synthesizing the next segment while the\ncurrent one plays.\n\nWith a streaming-capable player installed (see below), speech starts on the\nfirst bytes from the API instead of after the full download: about 0.3 s to\nthe first word regardless of length, versus 0.7 s for a short line and 2.5 s\nfor a long paragraph when buffered.\n\n## Voice mode for Claude Code\n\nThree pieces turn Claude Code into something you can walk away from: it\ntalks when it has news, and it calls you when it needs you.\n\n**1. Install the server** (Quick start above).\n\n**2. Tell Claude when to talk.** Add this to `~/.claude/CLAUDE.md`, or to\none project's CLAUDE.md:\n\n```markdown\n## Voice\n\nI have the Paxa MCP server (tools: speak, queue_speech, control_playback).\nI am often away from the screen, so use voice like this:\n\n- At the end of a turn where you did real work, call speak with a one or\n  two sentence summary before writing the final message: what you did,\n  what is next, and anything you need from me.\n- When you need a decision from me, speak the question too.\n- Keep it short and conversational. Never read code, file paths, logs, or\n  long lists aloud. Those stay in text.\n- Do not speak for quick back-and-forth or trivial answers.\n- If I ask to hear something long, use queue_speech.\n- Speak in the language I write in.\n```\n\n**3. Get told when Claude needs you.** When Claude Code waits for a\npermission or an answer, the model is not running, so it cannot call\nspeak. Claude Code fires a hook at those moments instead, and `paxa say`\nturns the hook into a spoken phrase such as \"Permission needed.\" Put\nthe `paxa` command on your PATH:\n\n```bash\nnpm install -g @paxalabs/mcp\n```\n\nThen add to `~/.claude/settings.json`:\n\n```json\n{\n  \"hooks\": {\n    \"Notification\": [\n      {\n        \"matcher\": \"permission_prompt|idle_prompt|agent_needs_input\",\n        \"hooks\": [{ \"type\": \"command\", \"command\": \"paxa say\" }]\n      }\n    ]\n  }\n}\n```\n\n`paxa say` takes the key from `PAXA_API_KEY`, or from the paxa entry in\n`~/.claude.json` when that is unset, so step 1 is all the setup it needs.\nA `Stop` hook configured the same way speaks \"Done.\" at the end of every\nturn.\n\nThe built-in phrases are synthesized once per voice and kept in your\nuser cache directory (`~/Library/Caches/paxa/say` on macOS,\n`~/.cache/paxa/say` on Linux, `%LOCALAPPDATA%\\paxa\\cache\\say` on\nWindows). After that first play, which costs well under one credit, a\nnotification plays from disk: no network round trip and no credits.\n\nTo change the words, write your own text in the hook command and add\n`--cache` so it gets the same treatment. One entry per event, since the\nmatcher picks the event:\n\n```json\n{\n  \"hooks\": {\n    \"Notification\": [\n      {\n        \"matcher\": \"permission_prompt\",\n        \"hooks\": [{ \"type\": \"command\", \"command\": \"paxa say --cache \\\"Hey, need your OK\\\"\" }]\n      },\n      {\n        \"matcher\": \"idle_prompt|agent_needs_input\",\n        \"hooks\": [{ \"type\": \"command\", \"command\": \"paxa say --cache --voice cookie \\\"Your turn\\\"\" }]\n      }\n    ]\n  }\n}\n```\n\nWithout `--cache`, nothing you type or pipe into `paxa say` is written to\ndisk, and messages carried inside a hook payload never are.\n\nOn macOS the built-in `afplay` needs about half a second just to start\nand stop, which is most of the delay you hear on a short phrase. With\n`brew install mpg123` (or `ffmpeg`) installed, cached phrases play\nthrough that instead: mpg123 starts in about 50 ms, ffplay in about 300 ms.\n\n`paxa say` also works on its own:\n\n```bash\npaxa say \"Build finished\"\npaxa say --voice cookie \"Deploy is live\"\n```\n\nIf your editor or desktop app was not launched from a terminal, its PATH\nmay not include your node bin directory, and the hook will fail silently.\nUse the absolute path to `paxa` in the hook command if that happens.\n\n## Environment variables\n\n| Variable | Required | Default | Purpose |\n| --- | --- | --- | --- |\n| `PAXA_API_KEY` | yes | | Your API key. The server starts without it, but every tool that calls the API then fails with setup instructions the agent can relay |\n| `PAXA_OUTPUT_DIR` | no | working directory | Where `text_to_speech` saves files |\n| `PAXA_DEFAULT_VOICE` | no | `nomyen` | Voice used when a tool call does not pick one. English text usually sounds best with an English voice (`donut`, `cookie`, `toast`, `latte`) |\n| `PAXA_BASE_URL` | no | `https://api.paxalabs.com` | API origin override |\n\n## Playback support\n\n| Platform | File player | Streaming player | Pause/resume |\n| --- | --- | --- | --- |\n| macOS | `afplay` (built in) | `ffplay`, `mpv`, or `mpg123` if installed | yes |\n| Linux | `ffplay`, `mpv`, `mpg123`, `paplay`, or `aplay` | `ffplay`, `mpv`, or `mpg123` | yes |\n| Windows | `ffplay` if installed, else PowerShell (wav) | `ffplay` if installed | no |\n\nStreaming needs a player that reads from stdin. On macOS, `brew install\nffmpeg` (or `mpv`) enables it; without one, speech still plays through\n`afplay` after the download completes. If no player is found at all, speech\ntools report it clearly and `text_to_speech` still works.\n\n## Claude Desktop extension\n\nEach release on GitHub ships a `.mcpb` bundle. Download it, open it with\nClaude Desktop, and enter your API key in the extension settings. The bundle\ncarries its own copy of the server and its dependencies, so it works without\nNode.js or npm on the machine.\n\n## Development\n\n```bash\npnpm install\npnpm build        # compile to dist/\npnpm typecheck\npnpm mcpb         # build release/paxalabs-mcp-<version>.mcpb for Claude Desktop\n\n# live smoke test (spends a few credits, plays audio out loud)\nPAXA_API_KEY=pxa_... TEST_OUT_DIR=/tmp/paxa-out node scripts/e2e.mjs\n```\n",
  "bytes": 10029,
  "sha": "fa7a6111d0a03ad5f02b24a70350e8f42ff9544614e7a4a688079d0da46a7e39",
  "repo_slug": "paxalabs/mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_paxalabs_mcp_4f5341f1/readme"
}