Paxa Labs

@paxalabs/mcp

适用于 Paxa Labs API 的官方 MCP 服务：为你的 Agent 提供泰语、英语和中文语音 AI，并支持本地音频播放。

连接到此服务的 Agent 可以通过你的设备扬声器朗读内容，将长篇内容作为托管播放队列朗读，将语音保存为音频文件，监听口头回复，转录录音并生成字幕，将任意语言翻译成泰语，使用 OCR 读取 PDF 和图像，并从文档中提取结构化字段。

Beta 版。 工具集已完整，并经过端到端测试，但在收集反馈的过程中，工具名称和行为在 1.0 版发布前仍可能发生变化。请在 https://github.com/paxalabs/mcp/issues 报告问题。

快速开始

你需要从 paxalabs.com 获取 Paxa API 密钥。新账户包含免费额度。

Claude Code

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

Claude Desktop、Cursor 和其他 MCP 客户端

将以下内容添加到客户端的 MCP 配置中（对于 Claude Desktop： claude_desktop_config.json）：

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

**Cursor 或 VS Code 一键安装：**这些按钮会将相同的配置项安装到 ~/.cursor/mcp.json 或 VS Code 的 MCP 设置中。然后将 paxa 配置项中的 pxa_your_key_here 替换为你的密钥。

工具

工具	功能	积分
speak	合成一小段语音并通过扬声器播放，直到播放完成后才返回	每 1000 个字符 10 积分（使用设计语音时为 12.5 积分）
queue_speech	大声朗读长内容：自动分块，播放期间提前合成，并立即返回	每 1000 个字符 10 积分（使用设计语音时为 12.5 积分）
control_playback	控制共享音频队列：status、pause、resume、skip、clear	免费
play_audio	通过扬声器播放本地音频文件	免费
text_to_speech	将语音合成为音频文件（mp3、opus、wav），但不播放：长脚本会拆分后合并为一个文件，subtitles 会生成匹配的 srt 或 vtt 字幕	每 1000 个字符 10 积分（带字幕或使用设计语音时为 12.5 积分，两者兼具时为 15 积分）
design_voice	根据文字描述创建新语音，并播放它朗读的内容	每次调用 5 积分
refine_voice	用文字调整草稿语音，例如“稍微低沉、缓慢一点”，并播放调整后的语音	每次调用 5 积分
save_voice	将草稿保存为你的语音之一，并分配一个语音工具可接受的 id	免费
rename_voice	重命名你设计的语音；id 和声音保持不变	免费
delete_voice	删除你设计的语音并释放其名额	免费
translate_to_thai	将任意语言翻译成泰语，并提供正式程度、术语表和上下文控制	每 1000 个字符 25 积分
ocr_document	将本地 PDF、PNG、JPEG 或 WebP 执行 OCR，转换为 Markdown 或结构化区块	每页 6.5 积分
extract_fields	从本地 PDF 或图像中提取填写类型化字段的架构（泰国身份证、日期、金额、银行、明细项）；每个值都会从文档中提取，否则返回 null 并说明原因	每页 13 积分（字段数超过 50 个的架构为 19.5 积分）
listen	录制一轮麦克风语音并返回转录文本；API 会检测用户何时停止说话	每分钟聆听 12.5 积分
send_feedback	对输出评分或向 Paxa 团队报告问题，并关联工具打印的请求 id	免费
transcribe_audio	将本地录音或视频（泰语、英语或混合语言）转录为文本，可选提供说话人标签、词语时间戳、srt 或 vtt 字幕，以及待剪切的停顿列表	每分钟 8.33 积分
list_voices	列出你设计的语音和名额，以及带有音色说明的 TTS 语音列表	免费
list_models	查看可用模型、限制和定价	免费
get_account	查看积分余额、套餐和速率限制	免费

所有音频都会通过同一个有序队列，因此声音不会重叠：speak 语句会插入到排队中的长篇内容之前，而 queue_speech 会在播放当前片段时合成下一个片段，让书籍或文章流畅播放、不间断。

安装支持流式播放的播放器后（见下文），语音会在 API 返回首批字节时开始播放，而不是等完整内容下载后才开始：无论内容长短，约 0.3 秒即可听到第一个词；相比之下，缓冲播放一小段语音需要 0.7 秒，播放一段长段落则需要 2.5 秒。

Claude Code 的语音模式

三个步骤让 Claude Code 成为你可以暂时离开的助手：有消息时会主动告诉你，需要你时会呼叫你。

1. 安装服务（见上方快速入门）。

2. 告诉 Claude 何时开口。 将以下内容添加到 ~/.claude/CLAUDE.md，或某个项目的 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. 在 Claude 需要你时收到通知。 Claude Code 等待权限或答案时，大模型不会运行，因此无法调用 speak。此时 Claude Code 会触发一个 hook，而 paxa say 会将该 hook 转换成语音短句，例如“需要权限”。将 paxa 命令添加到 PATH 中：

npm install -g @paxalabs/mcp

然后添加到 ~/.claude/settings.json：

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

paxa say 会从 PAXA_API_KEY 获取密钥；如果未设置，则从 ~/.claude.json 中的 paxa 条目获取，因此步骤 1 已完成所需的全部配置。按相同方式配置 Stop hook 后，每轮结束时都会播报“完成”。

内置短句会按语音合成一次，并保存在用户缓存目录中（macOS 上为 ~/Library/Caches/paxa/say，Linux 上为 ~/.cache/paxa/say，Windows 上为 %LOCALAPPDATA%\paxa\cache\say）。首次播放后（费用远低于 1 个额度），通知会从磁盘播放：无需网络往返，也不消耗额度。

如需更改播报内容，请在 hook 命令中写入自定义文本，并添加 --cache，即可获得相同的缓存处理。每个事件只能配置一条，因为匹配器会选择对应事件：

{
  "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\"" }]
      }
    ]
  }
}

不使用 --cache 时，你输入或通过管道传给 paxa say 的内容都不会写入磁盘，hook 负载中携带的消息也不会写入。

在 macOS 上，内置的 afplay 启动和停止大约需要半秒，这几乎占了短语音播放延迟的全部。安装 brew install mpg123（或 ffmpeg）后，缓存短句会通过它播放：mpg123 大约 50 毫秒即可启动，ffplay 大约需要 300 毫秒。

paxa say 也可以独立使用：

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

如果你的编辑器或桌面应用不是从终端启动的，其 PATH 可能不包含你的 node bin 目录，hook 也可能因此静默失败。遇到这种情况，请在 hook 命令中使用 paxa 的绝对路径。

语音模型

语音默认使用 Paxa TTS Flash v2：提供 50 种语音，每种都能说泰语、英语和中文普通话，并且每种语音都会朗读写在文本中的方向标签，例如 [whispering]、[laughs]、[speaking slowly, close to the microphone]、加权组合（如 [happy:0.7+sad:0.3]），或 <emph> 和 <whisper> 标记。方括号中的内容不会被朗读，标签字符会按文本计费，而模型无法实现的标签会在收费前被拒绝。方向指南列出了所有声音效果和规则。

仅在使用 v1 的旧版功能时，才在调用中传入 model: "paxa-tts-flash-v1"，或设置 PAXA_TTS_MODEL：四种带地区口音（伊森、北部、南部）的泰语语音、khanomchan 和 kaprao 上的固定情绪标签，或 v2 不包含的八种语音（donut、toast、padthai、yoyo、somtam、larb、khaosoi、roti）。两个版本的价格和限制相同。

设计你自己的声音

如果目录中的声音都不合适，可以描述你想要的声音。design_voice 会将一两句话（谁在说话、声音特点、将在哪里听到，以及说什么语言）转换成一种声音，并播放它说出的台词。refine_voice 每次只接受一项修改，例如“再低沉、缓慢一点”，其余声音特点保持不变；之前的草稿仍可使用，因此你可以回到之前的版本。save_voice 会将你喜欢的草稿保存到一个 id（voice_...）下，该 id 可用于 Paxa TTS Flash v2 的 speak、queue_speech 和 text_to_speech；将其设为 PAXA_DEFAULT_VOICE 即可将其设为默认声音。每次设计或修改需花费 5 个 credits，保存免费，使用设计的声音生成语音需花费 1.25 倍。你的套餐决定可保留的声音数量（Free 为 1 个，Starter 为 3 个，Standard 为 10 个，Pro 为 50 个）；list_voices 会显示这些声音及已占用的名额，rename_voice 可重命名声音，delete_voice 可释放名额。声音描述指南提供了一些示例。

内容创作

创作者提出的三个需求，每项都是 API 调用的本地部分：

• 转录视频。 将 mp4、mov、mkv 或大多数其他容器格式的文件传给 transcribe_audio；ffmpeg 会在本地提取音轨，再由 API 转录。添加 pauses_over: 0.7 后，结果会列出每段超过该时长的静音及其起止时间，也就是需要剪掉的空白片段。添加 save: ["srt"]，还会返回字幕。
• 生成与字幕匹配的配音。 使用 subtitles: "srt"（或 "vtt"）调用 text_to_speech，即可在音频旁生成字幕文件，时间戳根据合成语音生成。字幕条目会在句末标点、停顿和行数限制处换行，不会拆开单词；泰语则会在作者添加空格的位置结束一行。带时间戳的合成需按 1.25 倍计费。
• 将长篇旁白生成到一个文件中。 超过 5,000 个字符的脚本会按段落和句子拆分，逐段合成，再通过 ffmpeg 合并为一个 mp3、opus 或 wav 文件，并调整字幕时间戳使其匹配。

视频输入和分段合并都需要 ffmpeg（macOS 上可运行 brew install ffmpeg）。其他功能均无需 ffmpeg。

收听

listen 可以将麦克风输入转换为回答。使用 speak 提问，再调用 listen；用户停止说话后，其口述回复会立即以文本形式返回：Paxa 的实时转录功能会检测轮次结束，因此无需猜测静音时长。音频会直接发送至 API，绝不会写入磁盘。收听几秒钟的费用远低于 1 个 credit（每分钟 12.5 个 credits，包含静音时间）。

该功能需要命令行录音工具，而 macOS 和 Windows 默认均未提供：macOS 上可运行 brew install ffmpeg 或 brew install sox；Windows 上需要 sox（或搭配设置为 DirectShow 设备名称的 PAXA_MIC 使用 ffmpeg）；Linux 上需要 ffmpeg、sox、parecord 或 arecord。此外还需要 Node 22 或更高版本，并且启动服务的应用（Terminal、VS Code、Claude Desktop）必须具有麦克风权限。如果系统默认设备不是你想用的设备，可通过 PAXA_MIC 选择设备。如需在没有麦克风的情况下检查识别效果，可运行 node scripts/listen-file.mjs recording.mp3，通过同一会话处理文件。

环境变量

变量	必需	默认值	用途
PAXA_API_KEY	是		你的 API 密钥。服务可以在未配置密钥的情况下启动，但之后所有调用 API 的工具都会失败，并提供设置说明供 Agent 转达
PAXA_OUTPUT_DIR	否	工作目录	text_to_speech 保存文件的位置
PAXA_TTS_MODEL	否	paxa-tts-flash-v2	未指定模型的所有调用所使用的语音模型。v2 有 50 种音色，每种都能说泰语、英语和普通话，并且都会读取方向标签。仅在需要泰语地区口音、khanomchan 和 kaprao 上固定的情绪标签，或 v2 未提供的八种音色之一时，使用 paxa-tts-flash-v1
PAXA_DEFAULT_VOICE	否	foithong	工具调用未指定音色时使用的音色：来自 list_voices 的目录音色，或你设计的音色（voice_...）。在 v2 中，所有目录音色都能说这三种语言，因此请按角色挑选
PAXA_VOCABULARY	否		transcribe_audio 的关键词固定列表：以逗号分隔的名称和术语，转录文本应按原样拼写（产品名称、人名、行话）
PAXA_DEFAULT_SPEED	否	1	调用未指定语速时使用的语速，范围为 0.5 至 1.5。音调会保留，价格不变；长篇朗读适合使用 1.2 至 1.3
PAXA_MIC	否	系统默认值	listen 使用的麦克风设备：macOS 上的 AVFoundation 设备名称、Linux 上的 PulseAudio 或 ALSA 设备、Windows 上的 DirectShow 设备名称
PAXA_VOCABULARY_FILE	否		每行一个术语的文本文件（# 开头的行是注释），也会固定到每次转录中。每次调用时读取，因此修改后无需重启即可生效
PAXA_BASE_URL	否	https://api.paxalabs.com	覆盖 API 来源地址

若要为每个项目固定不同的列表，请在项目级服务条目中设置词汇表变量（Claude Code 的项目级作用域、.cursor/mcp.json、.vscode/mcp.json）。每次调用时，工具会优先使用调用本身提供的术语，然后使用已配置的术语；去重后截取至 API 限制的 50 个，并报告固定了多少个术语。

播放支持

平台	文件播放器	流式播放器	暂停/恢复
macOS	afplay（内置）	mpg123、ffplay 或 mpv（如果已安装）	是
Linux	ffplay、mpv、mpg123、paplay 或 aplay	mpg123、ffplay 或 mpv	是
Windows	ffplay（如果已安装），否则使用 PowerShell（wav）	mpg123、ffplay 或 mpv（如果已安装）	否

流式播放需要能从 stdin 读取的播放器。在 macOS 上，安装 mpg123（最快上手）或 ffmpeg 即可启用流式播放；若未安装，两者皆无时，语音仍会在下载完成后通过 afplay 播放。如果完全找不到播放器，语音工具会明确报告这一点，且 text_to_speech 仍可正常使用。

Claude Desktop 扩展

GitHub 上的每个版本都附带一个 .mcpb 捆绑包。下载后用 Claude Desktop 打开，并在扩展设置中输入你的 API 密钥。捆绑包自带服务及其依赖项，因此即使机器上没有 Node.js 或 npm，也能正常运行。

开发

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