Whisper Transcribe

whisper-transcribe-mcp

faster-whisper（ローカル、無料、オフライン）または OpenAI Whisper API（クラウド、API キーが必要）を使用して音声を書き起こす MCP サーバーです。macOS、Windows、Linux で Claude Desktop と Claude Code に対応しています。

---

前提条件

macOS

オプション A — uv（推奨）：

brew install uv
# or
curl -LsSf https://astral.sh/uv/install.sh | sh

オプション B — Python： Python 3.10+ は macOS 12.3+ に含まれています。brew install python でインストールすることもできます。

---

Windows

オプション A — uv（推奨）：

winget install astral-sh.uv

または astral.sh/uv からインストーラーをダウンロードしてください。

オプション B — Python： python.org から Python 3.10+ をダウンロードしてください。インストール時に 「Add Python to PATH」 にチェックを入れてください。

ffmpeg やコンパイラーをインストールする必要はありません。すべてパッケージにバンドルされています。

---

Linux

オプション A — uv（推奨）：

curl -LsSf https://astral.sh/uv/install.sh | sh

オプション B — Python：

# Debian/Ubuntu
sudo apt install python3.12 python3.12-venv

# Fedora
sudo dnf install python3.12

# Arch
sudo pacman -S python

追加のシステム依存関係は必要ありません。

---

インストール

オプション A — uvx（推奨、恒久的なインストール不要）

uvx はパッケージを分離された環境に自動的にダウンロードしてインストールします。必要なのは uv がインストールされていることだけです。

# Local backend:
uvx "whisper-transcribe-mcp[local]"

# OpenAI backend:
uvx "whisper-transcribe-mcp[openai]"

# Both backends:
uvx "whisper-transcribe-mcp[all]"

オプション B — pip

# Local backend:
pip install "whisper-transcribe-mcp[local]"

# OpenAI backend:
pip install "whisper-transcribe-mcp[openai]"

# Both backends:
pip install "whisper-transcribe-mcp[all]"

---

使用例

ケース 1 — ローカルバックエンドのみ（無料、オフラインで動作）

faster-whisper を使ってローカルで書き起こします。初回使用時にモデルが HuggingFace からダウンロードされ（base の場合は約 74MB）、キャッシュされます。

インストール：

pip install "whisper-transcribe-mcp[local]"

環境変数：

WHISPER_MODEL=base   # or tiny, small, medium, large-v3

---

ケース 2 — OpenAI バックエンドのみ（最高精度、API キーが必要）

OpenAI の whisper-1 モデルを使用します。API キーとインターネット接続が必要です。ローカルモデルはダウンロードされません。

インストール：

pip install "whisper-transcribe-mcp[openai]"

環境変数：

OPENAI_API_KEY=sk-...

---

ケース 3 — 両方のバックエンド（キーが設定されていれば OpenAI、フォールバックとしてローカル）

OPENAI_API_KEY が設定されている場合は、OpenAI が自動的に使用されます。設定されていない場合は、ローカルの faster-whisper にフォールバックします。

インストール：

pip install "whisper-transcribe-mcp[all]"

---

設定

Claude Desktop

OS ごとの設定ファイルの場所：

OS	パス
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

"mcpServers" 内にエントリーを追加します：

Windows に関する注意： Claude Desktop は制限された環境で実行されるため、PATH に uvx が含まれていない場合があります。また、ctranslate2（faster-whisper の依存関係）のビルド済みホイールがまだ用意されていない Python バージョン（例：3.14）を使用する場合があります。次の 2 つの対処が必要です：

1. uvx だけでなく、uvx.exe のフルパスを使用してください。PowerShell で where.exe uvx を実行すると確認できます（通常は C:\Users\<YourUser>\.local\bin\uvx.exe です）。
2. 互換性のあるホイールが使われるよう、--python 3.12 フラグで Python 3.12 を指定してください。

ケース 1 — ローカル：

macOS / Linux：

{
  "mcpServers": {
    "whisper-transcribe": {
      "command": "uvx",
      "args": ["whisper-transcribe-mcp[local]"],
      "env": {
        "WHISPER_MODEL": "base"
      }
    }
  }
}

Windows：

{
  "mcpServers": {
    "whisper-transcribe": {
      "command": "C:\\Users\\<YourUser>\\.local\\bin\\uvx.exe",
      "args": ["--python", "3.12", "whisper-transcribe-mcp[local]"],
      "env": {
        "WHISPER_MODEL": "base"
      }
    }
  }
}

ケース 2 — OpenAI：

macOS / Linux：

{
  "mcpServers": {
    "whisper-transcribe": {
      "command": "uvx",
      "args": ["whisper-transcribe-mcp[openai]"],
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Windows：

{
  "mcpServers": {
    "whisper-transcribe": {
      "command": "C:\\Users\\<YourUser>\\.local\\bin\\uvx.exe",
      "args": ["--python", "3.12", "whisper-transcribe-mcp[openai]"],
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

ケース 3 — 両方（キーが設定されている場合は OpenAI が優先）：

macOS / Linux：

{
  "mcpServers": {
    "whisper-transcribe": {
      "command": "uvx",
      "args": ["whisper-transcribe-mcp[all]"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "WHISPER_MODEL": "base"
      }
    }
  }
}

Windows：

{
  "mcpServers": {
    "whisper-transcribe": {
      "command": "C:\\Users\\<YourUser>\\.local\\bin\\uvx.exe",
      "args": ["--python", "3.12", "whisper-transcribe-mcp[all]"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "WHISPER_MODEL": "base"
      }
    }
  }
}

ファイルを編集した後、Claude Desktop を再起動してください。

---

Claude Code

macOS、Windows、Linux で同じように動作します。uv がインストールされている必要があります。

Claude Code の設定ファイルの場所：

OS	グローバル	プロジェクトごと
macOS / Linux	~/.claude.json	.claude/settings.json（プロジェクトのルート）
Windows	C:\Users\<user>\.claude.json	.claude\settings.json（プロジェクトのルート）

サーバーを追加する最も簡単な方法は、Claude Code CLI を使うことです。設定ファイルは自動的に更新されます。

# Case 1 — Local:
claude mcp add whisper-transcribe uvx -- "whisper-transcribe-mcp[local]"

# Case 2 — OpenAI:
claude mcp add whisper-transcribe uvx --env OPENAI_API_KEY=sk-... -- "whisper-transcribe-mcp[openai]"

# Case 3 — Both (OpenAI with local fallback):
claude mcp add whisper-transcribe uvx --env OPENAI_API_KEY=sk-... --env WHISPER_MODEL=base -- "whisper-transcribe-mcp[all]"

Windows + [all]： ctranslate2 のホイールに関する問題を避けるには、パッケージ名の前に --python 3.12 を追加してください。~/.claude.json を直接編集し、"args": ["--python", "3.12", "whisper-transcribe-mcp[all]"] を使用します。

グローバルに追加して（すべてのプロジェクトで利用できるようにして）使用するには、--scope user を指定します。

claude mcp add --scope user whisper-transcribe uvx -- "whisper-transcribe-mcp[local]"

または、~/.claude.json を直接編集し、"mcpServers" の中に追加します。

{
  "mcpServers": {
    "whisper-transcribe": {
      "command": "uvx",
      "args": ["whisper-transcribe-mcp[local]"],
      "env": {
        "WHISPER_MODEL": "base"
      }
    }
  }
}

---

環境変数

変数	デフォルト	説明
WHISPER_MODEL	base	ローカルモデルのサイズ：tiny、base、small、medium、large-v3
OPENAI_API_KEY	—	設定すると、ローカルではなく OpenAI バックエンドを有効にします
WHISPER_POST_PROCESS_MODEL	gpt-5.4-nano	post_process=true の場合に使用する OpenAI チャットモデル

バックエンドの選択とフォールバック（[all] のみ）

[all] を指定してインストールした場合、起動時にバックエンドが選択されます。

• OPENAI_API_KEY が設定されている → OpenAI が使用されます。実行時に API 呼び出しが失敗した場合（ネットワークエラー、無効なキー、クォータ超過など）、サーバーは自動的にローカルの faster-whisper にフォールバックし、レスポンスに "fallback_reason" フィールドを含めます。
• OPENAI_API_KEY が設定されていない → ローカルの faster-whisper が直接使用され、フォールバックは試行されません。

---

セキュリティと権限

サーバーはローカルで stdio 経由で実行され、各ツールが必要とするアクセス権限のみを必要とします。

アクセス	理由
ファイルシステムの読み取り	transcribe_file は、指定された音声ファイルのパスを読み取ります。
一時ファイル	transcribe_base64 は、デコードした音声をプライベートな一時ファイルに書き込み、必ず削除します。
ネットワーク	OpenAI バックエンド／後処理を使用する場合、および Hugging Face からローカルモデルを初めてダウンロードする場合にのみ必要です。
環境変数	OPENAI_API_KEY、WHISPER_MODEL、WHISPER_POST_PROCESS_MODEL。

ツールの入力は使用前に検証されます。model_size は既知の Whisper モデル名、language は ISO 639 コード、extension は既知の音声形式である必要があります。OpenAI のエラーは短い概要（エラー種別と HTTP ステータス）として返され、完全なメッセージは stderr に出力されます。 リリースは、PyPI Trusted Publishing と PEP 740 のプロベナンス証明を使用して GitHub Actions から公開されます。

---

利用可能なツール

transcribe_file

ファイルパスで指定した音声ファイル（mp3、wav、m4a、ogg、flac、webm など）を文字起こしします。

パラメーター：

• file_path（必須）：音声ファイルの絶対パス
• language（任意）：言語コード（es、en、fr など）。指定しない場合は自動検出されます。
• model_size（任意）：ローカルモデルのサイズ。OpenAI バックエンドでは無視されます。
• post_process（任意、デフォルトは false）：true の場合、文字起こし結果を GPT-4.1 に渡し、スペル、文法、句読点を修正します。openai パッケージ（[openai] または [all]）が必要です。
• post_process_prompt（任意）：GPT の後処理に使用するカスタムシステムプロンプトです。Whisper が誤って文字起こしする可能性のある専門分野の背景情報、固有名詞、製品名を指定できます。指定しない場合は、汎用の修正プロンプトが使用されます。

レスポンス（後処理なし）：

{
  "text": "Full transcription...",
  "language": "en",
  "language_probability": 0.99,
  "segments": [
    { "start": 0.0, "end": 4.2, "text": "First segment..." }
  ],
  "backend": "local",
  "model": "base"
}

レスポンス（post_process: true の場合）：

{
  "text": "Corrected transcription...",
  "raw_text": "Original transcription from Whisper...",
  "post_process_model": "gpt-4.1",
  "language": "en",
  "language_probability": 0.99,
  "segments": [...],
  "backend": "local",
  "model": "base"
}

後処理に失敗した場合、text には元の文字起こし結果が保持され、post_process_error フィールドが追加されます。

transcribe_base64

Base64 エンコードされた文字列で渡された音声を書き起こします。プログラムによる統合に便利です。

パラメーター：

• audio_base64（必須）：Base64 エンコードされた音声データ
• extension（任意、デフォルトは mp3）：ファイル拡張子（mp3、wav、ogg など）
• language（任意）：言語コード
• model_size（任意）：ローカルモデルのサイズ
• post_process（任意、デフォルトは false）：transcribe_file と同じです。
• post_process_prompt（任意）：transcribe_file と同じです。

---

list_models

有効なバックエンド構成、利用可能なローカルモデル、後処理に使用する GPT モデルを表示します。

---

ローカルモデルのサイズ

モデル	サイズ	相対速度	備考
tiny	39 MB	~32x	最速ですが、精度は最も低いです
base	74 MB	~16x	バランスに優れています（デフォルト）
small	244 MB	~6x	より高い精度
medium	769 MB	~2x	高精度
large-v3	1.5 GB	~1x	最高精度ですが、最も遅いです

モデルは初回使用時に HuggingFace から自動的にダウンロードされ、ローカルにキャッシュされます。

---

トラブルシューティング

Windows で Claude Desktop に MCP が読み込まれない

症状： 次のような依存関係の解決エラーが発生し、サーバーの起動に失敗します。

ctranslate2>=4.6.1 has no wheels with a matching platform tag (e.g., `win32`)
hint: You require CPython 3.14 (`cp314`), but we only found wheels for `ctranslate2` with: `cp39`, `cp310`, `cp311`, `cp312`, `cp313`

原因： 2 つの問題が重なっています。

1. Claude Desktop はユーザーのローカル bin を PATH に含めないため、uvx をフルパスで指定する必要があります。
2. Claude Desktop の uvx は、ctranslate2（faster-whisper のネイティブ依存関係）の Windows 用ビルド済みホイールがまだ存在しない Python バージョン（例：3.14）を選ぶ場合があります。

解決方法： uvx.exe のフルパスを使用し、Python 3.12 を明示的に指定します。

"whisper-transcribe": {
  "command": "C:\\Users\\<YourUser>\\.local\\bin\\uvx.exe",
  "args": ["--python", "3.12", "whisper-transcribe-mcp[local]"],
  "env": { "WHISPER_MODEL": "base" }
}

正確な uvx.exe のパスを確認するには、PowerShell で次を実行します。

where.exe uvx

Claude Desktop で音声ファイルを書き起こす

症状： Claude Desktop がアップロードされた音声ファイルの書き起こしに失敗します。ファイルを Base64 として読み込んで transcribe_base64 に渡そうとする場合があり、約 50 KB を超えるファイルでは処理が失敗するか、応答しなくなります。

原因： Claude Desktop はサンドボックス化された Linux コンテナ内で動作します。添付ボタンを使ってファイルをアップロードすると、ファイルは /mnt/user-data/uploads/audio.mp3 のようなコンテナ内のパスに保存されます。MCP サーバーは Windows マシン上で動作しており、そのコンテナ内のパスにはアクセスできません。Claude が代わりにファイルを Base64 エンコードして transcribe_base64 に渡す方法も、実際にはうまくいきません。小さな音声ファイルでも数百キロバイトの Base64 テキストが生成され、ツール呼び出しを行う前にコンテキストウィンドウを超えてしまうためです。

解決方法： 添付ボタンを使って音声ファイルをアップロードしないでください。代わりに、ファイルを Windows のファイルシステム上の任意の場所に置き、メッセージ内でそのパスを直接指定します。

"C:\Users\YourUser\Downloads\audio.mp3 にあるファイルを書き起こしてください"

MCP サーバーは Windows から直接ファイルを読み込み、書き起こしバックエンドに送信します。Whisper API の上限（25 MB）以内であれば、どのサイズのファイルでも処理できます。

---

開発

このプロジェクトでは、再現可能な開発環境のために uv を使用しています。

uv sync --group dev
uv run ruff check .
uv run ruff format --check .
uv run pytest -q
uv run pre-commit install

コントリビューションのワークフローについては、CONTRIBUTING.md を参照してください。

配布とリリース

このパッケージは PyPI を通じて配布され、 server.json によって 公式 MCP Registry に登録されています。バージョンタグを付けると、長期間有効な公開トークンを使わずに、GitHub OIDC を通じて両方の配布先に公開されます。リリースチェックリストと一度限りのリポジトリ設定については、docs/publishing.md を参照してください。

Registry のエントリーは、基本の PyPI パッケージについて説明しています。必要な書き起こしバックエンドをインストールするには、上記のインストール例から [local]、[openai]、または [all] の追加オプションを選択してください。

---

ライセンス

MIT — LICENSE を参照