macwhisper-mcp-server

macwhisper-mcp-server

MacWhisper と Claude Desktop を接続するローカル MCP サーバーです。

できること： 音声ファイルをデスクトップに置き、Claude に文字起こしや要約を依頼したり、アクションアイテムを抽出したりできます。すべてワンステップで完了します。文字起こしは MacWhisper が Mac 上で行い、内容の処理は Claude が行います。データがマシンの外に出ることはありません。クラウド API は使用しません。データが Mac の外に出ることは一切ありません。

Audio file  →  MacWhisper CLI  →  MCP server  →  Claude Desktop

---

---

必要条件

• macOS（MacWhisper は macOS 専用です）
• MacWhisper — インストールおよびライセンス認証済み
• MacWhisper CLI を有効化します。MacWhisper を開き、Settings → Advanced → Command-Line Tool → Install の順に選択してください。mw が /usr/local/bin/mw に配置されます。
• pyenv 経由の Python 3.13.x
• Claude Desktop

Homebrew 経由で MacWhisper をインストールする場合：

brew install --cask macwhisper

インストール後、上記の手順で MacWhisper の Settings から CLI を有効にします。後で brew upgrade --cask macwhisper を実行すると、CLI のシンボリックリンクが自動的に更新されるため、再インストールは不要です。

---

インストール

オプション A — Homebrew（推奨）

brew tap docdyhr/tap
brew install docdyhr/tap/macwhisper-mcp-server

これにより、Homebrew のプレフィックスに macwhisper-mcp バイナリがインストールされます。後でアップグレードするには、brew upgrade docdyhr/tap/macwhisper-mcp-server を実行してください。

オプション B — pip / ソース

pip install macwhisper-mcp-server

または、ソースからインストールします。

git clone https://github.com/docdyhr/macwhisper-mcp-server.git
cd macwhisper-mcp-server

pyenv install 3.13.13   # skip if already installed
pyenv local 3.13.13
python -m venv .venv
source .venv/bin/activate
pip install -e .

MacWhisper CLI にアクセスできることを確認します。

mw version

---

Claude Desktop の設定

~/Library/Application Support/Claude/claude_desktop_config.json を編集し、以下を追加します。

{
  "mcpServers": {
    "macwhisper": {
      "command": "macwhisper-mcp",
      "args": [],
      "env": {
        "MACWHISPER_ALLOWED_PATHS": "~/Desktop:~/Downloads",
        "FASTMCP_CHECK_FOR_UPDATES": "off"
      }
    }
  }
}

Claude Desktop を再起動します。

注： Claude に文字起こしを依頼する前に、音声ファイルを Mac のファイルシステム（デスクトップ、ダウンロード、または許可リストに登録された別のフォルダー）に保存する必要があります。Claude のチャットウィンドウに直接アップロードされたファイルは Claude のコンテナ内に保存されるため、ローカルの MacWhisper CLI からアクセスできません。

動作確認

Claude Desktop で、次のように依頼します。

~/Desktop/memo.m4a を文字起こししてください

transcribe_audio ツールの呼び出しに続いて、文字起こし結果が表示されます。

---

利用可能なツール

ツール	説明
transcribe_audio(path, model?, language?, persist?, engine?)	音声ファイルを文字起こしし、プレーンテキストで文字起こし結果を返します。language は ISO 639-1 コード（例：da）または auto です。ディレクトリごとのデフォルト設定より優先されます。persist=true にすると、MacWhisper の履歴に保存されます（MacWhisper エンジンのみ）。engine は "macwhisper"（デフォルト）または "whisper-cpp" です。詳しくは以下の代替エンジンをご覧ください。
list_models()	MacWhisper にインストールされている文字起こしモデルと、MACWHISPER_WHISPERCPP_MODEL_DIR が設定されている場合は whisper-cpp モデルを一覧表示します。有効な MacWhisper モデルには印が付きます。
cancel_transcription()	実行中の文字起こしをキャンセルします。
list_allowed_paths()	サーバーが読み取りを許可されているディレクトリを返します。
start_watch(folder)	フォルダーを監視し、新しい音声ファイルを ../done/ に自動で文字起こしします。
stop_watch()	実行中のフォルダー監視を停止します。
get_watch_results()	完了した監視フォルダーの文字起こし結果を返し、キューをクリアします。

対応する音声形式：.m4a .mp3 .mp4 .mov .wav .aiff .flac

---

設定

すべての設定は環境変数で行います。Claude Desktop の場合は claude_desktop_config.json の env 辞書で渡すか、ローカル開発の場合は .env に設定します。

環境変数	デフォルト	説明
MACWHISPER_ALLOWED_PATHS	~/Desktop	サーバーが読み取り可能なディレクトリをコロン区切りで指定します。
MACWHISPER_CLI	自動検出	mw バイナリへのパスです。ファイルが存在する場合は /Applications/MacWhisper.app/Contents/MacOS/mw、それ以外の場合は PATH 上の mw がデフォルトになります。
MACWHISPER_LOG_PATH	~/Library/Logs/macwhisper-mcp.log	ログファイルのパスです（標準出力には出力されません。標準出力は MCP 専用です）。
MACWHISPER_LANGUAGE_DEFAULTS	なし	dir=lang の組み合わせをコロン区切りで指定します（ISO 639-1、または auto）。一致するディレクトリ内のファイルには、--language が自動的に適用されます。最も具体的なディレクトリが優先されます。明示的に指定した language 引数は常に優先されます。
MACWHISPER_WHISPERCPP_BINARY	PATH 上の whisper-cli	whisper-cli バイナリが PATH 上にない場合に、そのパスを指定します。engine="whisper-cpp" の場合にのみ使用されます。
MACWHISPER_WHISPERCPP_MODEL_DIR	なし	GGML の .bin モデルファイルを含むディレクトリです。engine="whisper-cpp" を使用するには必須です。詳しくは以下をご覧ください。

ローカル開発： .env.example を .env にコピーして調整してください。direnv を使用すると、.envrc が .env を自動的にエクスポートします。direnv を使用しない場合は、source .env を実行してください。

ディレクトリごとの言語デフォルト設定

特定の言語の録音を定期的に文字起こしする場合は、呼び出しのたびに language を渡す代わりに、サブフォルダーをその言語に割り当てます。

"MACWHISPER_LANGUAGE_DEFAULTS": "~/Desktop/DK=da:~/Desktop/DE=de"

~/Desktop/DK/ にファイルを置くと、transcribe_audio が自動的に --language da を渡します。ツール呼び出しで明示的に指定した language 引数は、常にディレクトリのデフォルト設定より優先されます。

代替エンジン：whisper.cpp

transcribe_audio(..., engine="whisper-cpp") は、MacWhisper の代わりにスタンドアロンの whisper.cpp バイナリを使って文字起こしを行います。MacWhisper のライセンスをお持ちでない場合や、完全にオープンソースのローカル環境を使いたい場合に便利です。MacWhisper には一切触れません。

セットアップ：

brew install whisper-cpp

Homebrew でインストールされるのは whisper-cli バイナリのみで、モデルは含まれません。GGML モデルをご自身でダウンロードしてください（このサーバーがネットワーク経由で何かをダウンロードすることはありません）。ダウンロード元は huggingface.co/ggerganov/whisper.cpp です。たとえば ggml-base.en.bin を任意のディレクトリに保存し、サーバーにそのパスを指定します。

"MACWHISPER_WHISPERCPP_MODEL_DIR": "~/whisper-models"

次に、モデルのファイル名を指定してツールを呼び出します（MacWhisper の engine:model-id 形式の文字列ではありません）。

whisper-cpp エンジンとモデル ggml-base.en.bin を使って、~/Desktop/memo.wav を文字起こししてください

制限事項（v1）：

• 入力形式は .wav、.mp3、.flac のみです。.m4a／.mp4／.mov／.aiff には対応していません。これは whisper.cpp 本来の形式対応によるものです。ほかの形式は事前に変換する（たとえば ffmpeg を使用する）か、対応するすべての形式を処理できるデフォルトの MacWhisper エンジンを使用してください。
• persist=true には対応していません。whisper.cpp には履歴機能がありません。
• language もディレクトリのデフォルト設定も指定されていない場合、デフォルトの言語は英語（en）です。アプリ独自の言語設定に従う MacWhisper とは異なります。

---

開発

source .venv/bin/activate
pip install -e ".[dev]"

# Tests
pytest -q

# Lint + format
ruff check .
ruff format .

# Pre-commit hooks (one-time setup)
pip install pre-commit
pre-commit install

# Smoke-test against a real audio file (server must not be running in Claude Desktop)
python scripts/smoke_test.py ~/Downloads/Test.m4a

ログ

tail -f ~/Library/Logs/macwhisper-mcp.log

---

セキュリティ

• すべてのファイルパスは解決され（シンボリックリンクをたどります）、CLI に渡される前に MACWHISPER_ALLOWED_PATHS の許可リストと照合されます。
• subprocess.run は常に argv リストを使って呼び出されます。shell=True は決して使用しません。
• ネットワーク呼び出しは一切ありません。

脅威モデルの全容については、PRD §7 を参照してください。

---

既知の制限事項

• アップロードしたファイル： Claude のチャットウィンドウにドラッグしたファイルは Claude のコンテナ内に置かれるため、ローカルの MacWhisper CLI からはアクセスできません。ファイルをデスクトップまたはダウンロードフォルダー（あるいは許可リストに登録された別のディレクトリ）に保存してから、その場所にあるファイルの文字起こしを Claude に依頼してください。
• デンマーク語の文字名： Whisper は、文字名が単独で発音された場合、音声に基づいて近い音に置き換えて文字起こしすることがあります（例：「Æ、Ø、Å」→「E、Y、U」）。単語の中にある文字は正しく文字起こしされます。これは Whisper エンジンの制限であり、このラッパーの不具合ではありません。PRD §12 を参照してください。
• 初回起動時の遅延： MacWhisper の起動後、最初の文字起こしには約13秒かかります（モデルの読み込み）。以降の呼び出しは約2秒です。

---

ライセンス

MIT — LICENSE を参照してください。