mcp-speak

1.1.0で共有キュー、保留・破棄ミュート、AI向け使用方針を追加しました。

macOS標準の say コマンドを使い、MCPクライアントからテキストを読み上げるローカルサーバーです。読み上げ処理に外部の音声合成APIやAPIキーは使いません。

複数のClaude Codeスレッド・MCPプロセスからの依頼を、同じログインユーザーの共有ワーカーで順番に再生します。Rustや別の音声サーバーの導入は不要です。

初めて使う場合は「必要な環境」「インストール」「MCPクライアントへの登録」の順に進めてください。ツールの引数や開発手順は、必要なときに参照できます。

必要な環境

• macOS（/usr/bin/say が利用可能な環境）

• Node.js 22以上とnpm

• ローカルの標準入出力（stdio）接続に対応したMCPクライアント

音声は、このサーバーを実行するMacから再生されます。音声ファイルやストリームをクライアントへ送る機能はありません。

Related MCP server: mcp-speak

インストール

git clone https://github.com/mumei/mcp-speak.git
cd mcp-speak
npm ci

package-lock.json をGitで管理し、npm ci で依存関係を再現します。npmレジストリへの公開は行っていないため、GitHubから取得してください。

MCP受付プロセスを手動で起動する場合は、次のコマンドを使います。

npm start

起動後はMCPクライアントからの入力を待ちます。ターミナルに通常の文章を入力して読み上げるCLIではありません。終了は Ctrl+C です。Claude Codeに登録した場合はClaude Codeが受付プロセスを起動するため、通常は npm start の手動実行は不要です。

MCPクライアントへの登録

Claude Codeのコマンド登録

上記の npm ci を済ませてから登録します。まず claude mcp get mcp-speak または claude mcp list で、同名の登録がないか確認してください。登録済みの場合は内容を確認し、削除・上書きせずに既存の設定を使えるか判断します。

新規登録のコマンドは次のとおりです。

claude mcp add --transport stdio --scope user mcp-speak -- "/absolute/path/to/node" "/absolute/path/to/mcp-speak/index.js"

command -v node でNode.jsの場所を確認し、例の2つのパスをNode.jsと取得した index.js の絶対パスに置き換えてください。空白を含むパスも渡せるよう、引用符は残します。

--scope user は、同じユーザーの全プロジェクトで使うための登録先です。-- より後ろは、MCPサーバーを起動するコマンドと引数です。

登録後は、次のコマンドで登録内容と接続状態を確認できます。Claude Code内では /mcp でも確認できます。

claude mcp get mcp-speak
claude mcp list

登録形式・スコープ・確認方法は Claude Code公式のMCPドキュメント を参照してください。

設定ファイルの登録例

クライアントの設定に、次のようなstdioサーバーを登録します。設定キーや保存先はクライアントによって異なります。

{
  "mcpServers": {
    "mcp-speak": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/mcp-speak/index.js"]
    }
  }
}

command -v node でNode.jsの場所を確認し、command をその絶対パスに置き換えてください。args も取得した index.js の絶対パスにします。クライアントの作業ディレクトリやGUIアプリのPATHに依存せず起動できます。

各Claude Codeスレッドには、このstdio設定をそのまま使えます。各スレッドのMCPプロセスは別々に起動しても、再生ワーカーは1つです。クライアント設定や CLAUDE.md、hooksをこのプロジェクトが書き換えることはありません。

MCP受付と共有再生ワーカー

Claude Code A → MCPプロセスA ─┐
                            ├→ 共通FIFO → 再生ガード → say（1つずつ）
Claude Code B → MCPプロセスB ─┘

MCPプロセスは入力検証・キュー受付・操作を担当します。共有ワーカーは受け取った順に依頼を並べ、前の say の終了を確認してから次を再生します。同時送信の順番はワーカーが受け取った順番です。他アプリが直接起動した say や別ログインユーザーの音声は、このキューの対象外です。

最初のキュー操作で、画面のないNode製ワーカーが自動で起動します。通常は npm run worker の手動実行も不要です。最後のクライアントが切断し、再生・待機分がなくなると60秒後に終了します。Web GUI・メニューバーUI・ログイン時の自動起動登録はありません。手動で起動したい場合は npm run worker を使い、終了は Ctrl+C です。

接続先は 127.0.0.1 のみです。既定ポートは 43000 + ユーザーID % 1000 で、OSの排他的bindにより二重起動を防ぎます。/tmp/mcp-speak-<ユーザーID>-v1 に権限700の専用ディレクトリを作り、権限600のランダムトークンで認証します。同じOSユーザーによる操作は信頼境界の内側です。

テストなどで変える場合は、全クライアントに同じ MCP_SPEAK_QUEUE_DIR（絶対パス）と MCP_SPEAK_QUEUE_PORT を設定します。別のディレクトリやポートに分けると共通FIFOを共有できません。既定ポートを他アプリが使っている場合は、そのアプリを停止する代わりに共通の別ポートを指定してください。

ツールと引数

speak：テキストの読み上げ

{
  "text": "作業が完了しました。",
  "voice": "Kyoko",
  "rate": 175
}

Kyoko は例です。使用する音声は list_voices で確認してください。音声の追加や既定音声の変更はmacOS側で行います。

テキストは say の標準入力へ渡すため、先頭の - やシェルの記号をコマンドの引数として扱いません。未対応の引数、不正な型、範囲外の速度は isError: true で返します。

list_voices：利用可能な音声一覧

引数は不要です。空オブジェクト {} でも呼び出せます。音声名・言語・サンプル文章を含む一覧を返します。

ターミナルから音声を確認する場合は、次のコマンドも使えます。

say -v '?'

応答は再生完了を保証しません

speak は共通FIFOへの受付後に応答し、受付IDとその時点の順番を返します。応答は再生開始・完了を意味しません。破棄ミュート中は、再生せず破棄したことを返します。受付後の失敗は依頼元MCPの標準エラーへ記録します。

再生中と待機分を合わせて100件までです。満杯になった場合は新しい依頼を isError: true で拒否し、既存の順番を保ちます。1件の再生は最大120秒で停止します。再生完了を待つMCPツールはありません。

状態・停止・ミュートを操作する

どちらのミュートも途中の発声を再キューしません。保留から破棄へ切り替えると待機分を消します。破棄から保留へ切り替えると、その後の新規依頼から保持します。OSの音量や他アプリの音声は変更しません。

ミュート状態・モードは権限600の mute-state.json に保存し、ワーカーが再起動しても維持します。待機テキストはメモリ内だけに保持し、ディスクへ保存しません。

ターミナルからも同じ操作が可能です。状態確認CLIはワーカーを新しく起動しません。

npm run queue:status
npm run queue:mute -- hold
npm run queue:mute -- discard
npm run queue:unmute
npm run queue:stop
npm run queue:shutdown

queue:shutdown はこの共有ワーカーを終了します。接続中のMCPは切断され、次の操作で接続し直します。ミュートは自動解除しません。

AIへ発話の使い方を伝える

MCP初期化応答の正式な instructions フィールドと、tools/list のツール説明・入力説明に、AI向けの使用方針を載せています。対応クライアントではMCP登録と接続だけで受け取れます。方針を受け取るためにClaude側の CLAUDE.md やhooksの追加は必須ではありません。ただし、クライアントが指示をモデルへ渡すことや、AIが必ず従うことは保証できません。

方針は「必要な完了報告」「問題やユーザー判断が必要な場面」「明示された読み上げ依頼」に、短い要点だけを発話するものです。細かな途中経過・長いコード・生ログ・認証情報を読まず、同じ内容を繰り返しません。ユーザーのミュートや停止を尊重し、AIが勝手に解除・モード変更・再送しないよう伝えます。

キューを導入しただけではAIの自動発話は始まりません。AIが使用方針を踏まえて speak を呼ぶことで再生されます。

切断・失敗・異常終了

MCP接続が切断すると、その接続が依頼した待機分と再生中の発声だけをキャンセルします。他クライアントの待機分は維持します。受付前のMCPリクエスト取消にも対応します。受付後の発声は stop_speech などで操作してください。通常の再生失敗・キャンセルでは、所有する say の終了を確認してから次へ進みます。

ワーカーが強制終了しても、再生ガードが親との切断を検知し、自分が起動した say だけを停止します。別ワーカーは playback.json が解放されるまで次を始めません。ガード自体が強制終了するなど、前の発声の停止を確認できない場合は、新規再生を拒否して異常状態を返します。killall say は使いません。

異常状態では queue:status を確認し、queue:shutdown でワーカーを終了してください。自分のツールの発声が停止したと確認できた場合だけ、専用ディレクトリに残った playback.json を削除して再起動します。停止確認なしに再生記録を消すと音声が重なるおそれがあります。認証トークンを削除するとクライアント間の認証が変わるため、復旧時にディレクトリ全体を削除しないでください。

ワーカーの異常終了や接続喪失では、未完了の受付分を自動再送しません。待機分は失われる場合があります。ミュート状態は保存済みの設定を維持します。

開発とテスト

npm ci
npm run check
npm test

npm test はNode.js標準のテストランナーを使います。専用の一時ディレクトリ・ポート・疑似プレイヤーで、2つの実MCPプロセスのFIFOと重複なし、ミュート2モードと切替、上限、停止・切断・ワーカー強制終了、認証、初期化のAI向け方針を検査します。通常のテストで音声は再生しません。

Macの実際の say とMCP接続を確認するには、次を実行します。短い音声を1回再生するため、音を出せる環境で実行してください。

npm run test:smoke

スモークテストは接続、音声一覧、不正入力の拒否、読み上げの受付を検査します。再生完了や音質は検査しません。接続を閉じるとその発声がキャンセルされるため、実際の再生確認には2クライアント検証を使います。

npm run test:queue:smoke

専用の一時ディレクトリ・ポートを使い、独立した2つのMCPプロセスから「一番です。」「二番です。」だけを送ります。実際の say の正常終了と、前の再生終了後に次が始まることを検査します。普段使っている共有キューやミュート設定には触れません。

GitHub Actionsでも、macOS上のNode.js 22・24で構文チェックと自動テストを実行します。CIでは音声再生を伴うスモークテストを実行しません。

配布内容の確認には npm pack --dry-run を使います。パッケージには実装・README・LICENSEのみを含め、IDE設定、テスト、ローカル設定は除外します。

問題が起きたとき

接続できない場合は、登録したNode.jsと index.js のパス、npm ci の完了を確認してください。音が出ない場合は、Macの出力先・音量と say 'テストです' の動作を確認します。標準エラーのログには、受付後に発生した音声処理の失敗も出力されます。

不具合の報告は GitHub Issues へお願いします。macOSとNode.jsのバージョン、再現手順を添え、読み上げ文章に含まれる個人情報や秘密情報は伏せてください。

MCPはアプリからツールを呼び出すためのプロトコルです。このサーバーのstdio接続では、標準入力でリクエストを受け、標準出力で応答を返します。ログには標準エラーを使います。

ライセンス

MIT。既存の package.json のライセンス指定に合わせています。