Paxa Labs

@paxalabs/mcp

Paxa Labs API公式のMCPサーバーです。エージェント向けに、ローカルでの音声再生を含む、タイ語、英語、中国語（標準語）の音声 AI を提供します。

このサーバーに接続したエージェントは、マシンのスピーカーから音声を再生したり、長いコンテンツを管理された再生キューで読み上げたり、音声をファイルに保存したり、音声での返答を聞き取ったり、録音を字幕付きで文字起こししたり、あらゆる言語をタイ語に翻訳したり、OCR で PDF や画像を読み取ったり、文書から型付きフィールドを抽出したりできます。

ベータ版です。 ツールセットはすべて揃っており、エンドツーエンドでテスト済みですが、フィードバックに応じて 1.0 リリースまでにツール名や動作が変更される場合があります。問題は https://github.com/paxalabs/mcp/issues までご報告ください。

クイックスタート

Paxa Labs から 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）に合成します。長いスクリプトは分割して 1 つのファイルに結合し、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 または構造化ブロックに変換します	1 ページあたり 6.5
extract_fields	ローカルの PDF または画像から、型付きフィールドのスキーマ（タイの ID、日付、金額、銀行、明細項目）に値を入力します。各値は文書に記載された値、または理由を添えた null として出力されます	1 ページあたり 13（50 フィールドを超えるスキーマでは 19.5）
listen	マイクから発話 1 回分を録音して文字起こしを返します。API はユーザーが話し終えたタイミングを検知します	聴取 1 分あたり 12.5
send_feedback	ツールが出力するリクエスト ID に紐づけて、出力を評価するか、Paxa チームに問題を報告します	無料
transcribe_audio	ローカルの録音または動画をテキストに文字起こしします（タイ語、英語、混在）。話者ラベル、単語ごとのタイミング、srt または vtt 字幕、カットする無音区間のリストも指定できます	1 分あたり 8.33
list_voices	作成した音声とスロット、さらに音声の特徴メモ付き TTS 音声一覧を表示します	無料
list_models	利用可能なモデル、制限、料金を表示します	無料
get_account	クレジット残高、プラン、レート制限を表示します	無料

すべての音声は 1 つの順序付きキューを通るため、音声が重なることはありません。speak の文章はキューに入った長文セグメントの前に割り込み、queue_speech は現在のセグメントの 再生中に次のセグメントを合成するため、本や記事を途切れなく読み進められます。

ストリーミング対応プレーヤーがインストールされている場合（下記参照）、ダウンロードの 完了を待たず、API から最初のバイトが届いた時点で読み上げが始まります。長さにかかわらず 最初の単語まで約 0.3 秒です。バッファリング方式では、短い文章で 0.7 秒、長い段落で 2.5 秒かかります。

Claude Code の音声モード

Claude Code を、席を離れても使えるようにするための仕組みが3つあります。知らせがあると音声で伝え、あなたの対応が必要になると呼びかけます。

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 がフックを実行し、paxa say がフックを「許可が必要です」のような音声フレーズに変換します。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 フックは、各ターンの終了時に「完了しました」と読み上げます。

組み込みフレーズは音声ごとに一度だけ合成され、ユーザーのキャッシュディレクトリ（macOS では ~/Library/Caches/paxa/say、Linux では ~/.cache/paxa/say、Windows では %LOCALAPPDATA%\paxa\cache\say）に保存されます。初回の再生にかかる費用は1クレジットを大きく下回ります。それ以降、通知はディスクから再生されるため、ネットワークへの往復もクレジットも不要です。

読み上げる内容を変更するには、フックコマンドにテキストを指定し、同じように処理されるよう --cache を追加します。マッチャーはイベントを判定するため、イベントごとにエントリを1つ設定してください。

{
  "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 に入力したテキストやパイプで渡したテキストがディスクに書き込まれることはありません。また、フックのペイロードに含まれるメッセージも書き込まれません。

macOS の組み込みコマンド afplay は、起動と停止だけで約0.5秒かかるため、短いフレーズでは遅延の大部分を占めます。brew install mpg123（または ffmpeg）をインストールすると、キャッシュされたフレーズは代わりにそちらを使って再生されます。mpg123 の起動には約50ミリ秒、ffplay の起動には約300ミリ秒かかります。

paxa say は単独でも使えます。

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

エディターやデスクトップアプリをターミナルから起動していない場合、PATH に node の bin ディレクトリが含まれておらず、フックがエラーを出さずに失敗することがあります。その場合は、フックコマンドで 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 を設定してください。v1 のレガシー機能には、地域アクセント（イーサーン、北部、南部）を持つ4種類のタイ語音声、khanomchan と kaprao の固定感情タグ、または v2 に含まれていない8種類の音声（donut、toast、padthai、yoyo、somtam、larb、khaosoi、roti）があります。どちらのバージョンも価格と制限は同じです。

独自の音声をデザインする

カタログの音声にぴったりのものがない場合は、作りたい音声を説明してください。design_voice は、話し手が誰か、どんな声か、どこで聞かれるのか、どの言語を話すのかを含む1、2文から音声を作成し、その音声で話した音声を再生します。refine_voice では、「少し低く、ゆっくり」のように一度に1つの変更を指定でき、それ以外の声はそのまま保たれます。以前のドラフトも引き続き使えるため、前のものに戻すこともできます。気に入ったドラフトは save_voice で ID（voice_...）を付けて保存でき、Paxa TTS Flash v2 では speak、queue_speech、text_to_speech でその ID を指定できます。PAXA_DEFAULT_VOICE に設定すると、デフォルトになります。デザインや変更にはそれぞれ5クレジットかかり、保存は無料です。デザインした音声での音声生成には1.25倍の料金がかかります。保存できる音声の数はプランによって異なります（Freeは1件、Starterは3件、Standardは10件、Proは50件）。list_voices では保存済みの音声と使用中の枠を確認でき、rename_voice で名前を変更し、delete_voice で削除して枠を空けられます。音声の説明ガイドに例があります。

コンテンツ作成

クリエイターから要望のあった3つの機能を、それぞれAPI呼び出しのローカル側で実行します。

• 動画を書き起こします。 mp4、mov、mkv、その他ほとんどのコンテナ形式のファイルを transcribe_audio に渡すと、ffmpeg がローカルで音声トラックを抽出し、API が書き起こします。pauses_over: 0.7 を追加すると、それより長いすべての無音区間について開始時刻と終了時刻が結果に表示され、カットすべき無音部分を確認できます。save: ["srt"] を指定すると、字幕も返されます。
• 字幕とタイミングが一致するナレーションを作成します。 text_to_speech に subtitles: "srt"（または "vtt"）を指定すると、合成した音声の隣に字幕ファイルが作成され、合成された単語に合わせてタイミングが設定されます。字幕の区切りは、文末の句読点、ポーズ、行の上限に合わせて設定され、単語の途中で分割されることはありません。タイ語の行は、原文でスペースが置かれた位置で終わります。タイミング付きの音声合成には1.25倍の料金がかかります。
• 長いナレーションを1つのファイルにまとめます。 5,000文字を超える原稿は段落や文の区切りで分割され、パートごとに合成された後、ffmpeg で1つの mp3、opus、または wav に結合されます。字幕のタイミングもそれに合わせて調整されます。

動画入力とパートの結合には ffmpeg が必要です（macOS では brew install ffmpeg）。それ以外の機能は ffmpeg なしで動作します。

聞き取り

listen を使うと、マイクを通じて返答を受け取れます。speak で質問し、listen を呼び出すと、ユーザーが話し終えた時点で音声の返答がテキストとして返されます。Paxa のリアルタイム文字起こしが発話の終了を検出するため、無音を推測する必要はありません。音声は直接APIに送信され、ディスクには書き込まれません。数秒の聞き取りにかかる料金は1クレジットを大きく下回ります（無音を含めて1分あたり12.5クレジット）。

標準の macOS と Windows には付属していないコマンドライン録音ツールが必要です。macOS では brew install ffmpeg または brew install sox、Windows では sox（または PAXA_MIC に DirectShow デバイス名を設定した 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 を呼び出す各ツールは失敗し、エージェントが伝えられるセットアップ手順が表示されます
PAXA_OUTPUT_DIR	いいえ	作業ディレクトリ	text_to_speech がファイルを保存する場所です
PAXA_TTS_MODEL	いいえ	paxa-tts-flash-v2	モデルを指定しないすべての呼び出しで使う音声モデルです。v2 には、タイ語、英語、標準中国語をそれぞれ話し、すべての読み上げ指示タグに対応する音声が 50 種類あります。paxa-tts-flash-v1 は、タイ語の地域アクセント、khanomchan と kaprao の固定された感情タグ、または v2 に含まれない 8 種類の音声を使う場合に限ります
PAXA_DEFAULT_VOICE	いいえ	foithong	ツール呼び出しで音声を指定しない場合に使う音声です。list_voices に表示されるカタログ音声、または自分でデザインした音声（voice_...）を指定できます。v2 では、どのカタログ音声も 3 言語すべてを話すため、キャラクターで選んでください
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	いいえ		1 行につき 1 つの用語を記載するテキストファイルです（# でコメントを開始します）。すべての文字起こしにこの用語も指定されます。呼び出し時に読み込まれるため、再起動せずに編集内容が反映されます
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	いいえ

ストリーミングには、標準入力から読み込めるプレーヤーが必要です。macOS では brew install 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