MCP Server Whisper

MCP Server Whisper

警告

このプロジェクトは移転しました。 現在の開発は TJC-LP/sanzaru に移行しました。このリポジトリは保守されなくなり、アーカイブされる予定です。依存関係と課題の報告先を新しいリポジトリに変更してください。

概要

MCP Server Whisperは、OpenAIの最新の文字起こしおよび音声サービスを通じて音声ファイルを処理する標準化された方法を提供します。Model Context Protocolを実装することで、ClaudeなどのAIアシスタントが音声処理機能をシームレスに利用できるようになります。

主な機能：

• 🔍 正規表現パターン、ファイルメタデータによるフィルタリング、並べ替え機能を備えた高度なファイル検索
• ⚡ MCPネイティブの並列処理 — 複数のツールを同時に呼び出し可能
• 🔄 対応する音声形式間の形式変換
• 📦 サイズ超過ファイルの自動圧縮
• 🎯 OpenAIのすべての音声モデルに対応したマルチモデル文字起こし
• 🗣️ GPT-4o音声モデルによる対話型音声チャット
• ✏️ 専用プロンプトとタイムスタンプに対応した文字起こしの強化
• 🎙️ 音声、指示、速度をカスタマイズできるテキスト読み上げ生成
• 📊 再生時間、ファイルサイズ、形式の対応状況を含む包括的なメタデータ
• 🚀 繰り返しの操作に対応する高性能キャッシュ
• 🔒 すべてのツール出力にPydanticモデルを使用した型安全な応答

注： このプロジェクトは非公式であり、OpenAIとは提携、承認、または後援関係にありません。OpenAIが一般公開しているAPIにModel Context Protocolインターフェースを提供します。

インストール

# Clone the repository
git clone https://github.com/arcaputo3/mcp-server-whisper.git
cd mcp-server-whisper

# Using uv 
uv sync

# Set up pre-commit hooks
uv run pre-commit install

環境設定

用意されている .env.example を基に .env ファイルを作成します。

cp .env.example .env

.env を実際の値で編集します。

OPENAI_API_KEY=your_openai_api_key
AUDIO_FILES_PATH=/path/to/your/audio/files

注： 環境変数は実行時に利用可能である必要があります。Claudeを使ったローカル開発では、dotenv-cli などのツールを使って環境変数を読み込んでください（下記の「使用方法」を参照）。

使用方法

Claudeを使ったローカル開発

このプロジェクトには、Claudeを使ったローカル開発用の .mcp.json 設定ファイルが含まれています。使用するには、次の手順に従ってください。

1. .env ファイルに必要な環境変数が設定されていることを確認します
2. 環境変数を読み込んだ状態でClaudeを起動します。

bunx dotenv-cli -- claude

これにより、次の処理が行われます。

• .env ファイルから環境変数を読み込みます
• .mcp.json の設定に従ってMCPサーバーを構成し、Claudeを起動します
• 開発中のホットリロードを有効にします

.mcp.json の設定：

{
  "mcpServers": {
    "whisper": {
      "command": "uv",
      "args": ["run", "mcp-server-whisper"],
      "env": {
        "OPENAI_API_KEY": "${OPENAI_API_KEY}",
        "AUDIO_FILES_PATH": "${AUDIO_FILES_PATH}"
      }
    }
  }
}

公開されるMCPツール

音声ファイル管理

• list_audio_files — 高度なフィルタリングおよび並べ替えオプションを使って音声ファイルを一覧表示します。
  • ファイル名に対する正規表現パターンマッチングでフィルタリング
  • ファイルサイズ、再生時間、更新日時、または形式でフィルタリング
  • 名前、サイズ、再生時間、更新日時、または形式で並べ替え
  • 完全なメタデータを含む、型安全な FilePathSupportParams を返します
• get_latest_audio — 最も新しく更新された音声ファイルを、モデルの対応情報とともに取得します

音声処理

• convert_audio — 音声ファイルを対応形式（mp3またはwav）に変換します
  • 出力パスを含む AudioProcessingResult を返します
• compress_audio — サイズ制限を超える音声ファイルを圧縮します
  • 出力パスを含む AudioProcessingResult を返します

文字起こし

• transcribe_audio - OpenAIのモデルを使用した高度な文字起こし：

  • whisper-1、gpt-4o-transcribe、gpt-4o-mini-transcribeをサポートします
  • ガイド付き文字起こし用のカスタムプロンプト
  • 単語およびセグメント単位のタイミングを指定する、任意のタイムスタンプ粒度
  • JSONレスポンス形式のオプション
  • テキスト、使用状況データ、任意のタイムスタンプを含むTranscriptionResultを返します

• chat_with_audio - GPT-4oのオーディオモデルを使用した対話型の音声分析：

  • gpt-4o-audio-preview（推奨）と日付付きバージョンをサポートします
  • 注意：gpt-4o-mini-audio-previewは音声チャットに制限があるため、推奨されません
  • カスタムのシステムプロンプトとユーザープロンプト
  • 音声コンテンツに対する対話形式の応答を提供します
  • 応答テキストを含むChatResultを返します

• transcribe_with_enhancement - 専用テンプレートを使用した拡張文字起こし：

  • detailed - トーン、感情、背景の詳細を含みます
  • storytelling - 文字起こしを物語形式に変換します
  • professional - フォーマルでビジネスに適した文字起こしを作成します
  • analytical - 話し方のパターンと要点の分析を追加します
  • 拡張された出力を含むTranscriptionResultを返します

テキスト読み上げ

• create_audio - OpenAIのTTS APIを使用してテキスト読み上げ音声を生成します：
  • gpt-4o-mini-tts（推奨）とその他の音声モデルをサポートします
  • 複数の音声オプション（alloy、ash、ballad、coral、echo、sage、shimmer、verse、marin、cedar）
  • 速度の調整とカスタム指示
  • 出力ファイルパスをカスタマイズできます
  • 音声セグメントを自動的に分割・結合し、長さを問わずテキストを処理します
  • 出力パスを含むTTSResultを返します

サポートされている音声形式

注意： 25MBを超えるファイルは、APIの制限に合わせて自動的に圧縮されます。

Claudeでの使用例

Claude, please transcribe my latest audio file with detailed insights.

Claude, list all my audio files that are longer than 5 minutes and were created after January 1st, 2024, sorted by size.

Claude, find all MP3 files with "interview" in the filename and create professional transcripts for each one.

Claude, create audio with this script: "Welcome to our podcast! Today we'll be discussing artificial intelligence trends in 2025." Use the shimmer voice.

Claude Desktopでの設定

ローカル開発ではなく、Claude Desktopを本番環境で使用する場合は、次の内容をclaude_desktop_config.jsonに追加します：

UVX

{
  "mcpServers": {
    "whisper": {
      "command": "uvx",
      "args": ["mcp-server-whisper"],
      "env": {
        "OPENAI_API_KEY": "your_openai_api_key",
        "AUDIO_FILES_PATH": "/path/to/your/audio/files"
      }
    }
  }
}

推奨（Mac OS のみ）

• Screen Recorder By Omi をインストールします（無料）
• AUDIO_FILES_PATH を /Users/<user>/Movies/Omi Screen Recorder に設定し、<user> をユーザー名に置き換えます
• アプリで音声を録音しながら、Claude で複数のファイルを並行して文字起こしできます

開発

このプロジェクトでは、uv、pytest、ruff、mypy などの最新の Python 開発ツールを使用しています。

# Run tests
uv run pytest

# Run with coverage
uv run pytest --cov=src

# Format code
uv run ruff format src

# Lint code
uv run ruff check src

# Run type checking (strict mode)
uv run mypy --strict src

# Run the pre-commit hooks
pre-commit run --all-files

CI/CD ワークフロー

このプロジェクトでは、CI/CD に GitHub Actions を使用しています。

1. Lint & Type Check：ruff と厳格な mypy の型チェックにより、コード品質を確保します
2. Tests：複数の Python バージョン（3.10、3.11、3.12、3.13、3.14、3.14t）でテストを実行します
3. Release & Publish：柔軟なリリース管理を可能にする、2 つのトリガーによるワークフローです

注： Python 3.14t は、真の並列処理をテストするためのフリースレッドビルド（GIL なし）です。

新しいリリースの作成

リリースワークフローでは、次の 2 つの方法を利用できます。

オプション 1：自動リリース（推奨）

タグをプッシュすると、リリースが自動的に作成され、PyPI に公開されます。

# 1. Update version in pyproject.toml
# Edit the version field manually, e.g., "1.0.0" -> "1.1.0"

# 2. Update __version__ in src/mcp_server_whisper/__init__.py to match

# 3. Update the lock file
uv lock

# 4. Commit the version bump
git add pyproject.toml src/mcp_server_whisper/__init__.py uv.lock
git commit -m "chore: bump version to 1.1.0"

# 5. Create and push the version tag
git tag v1.1.0
git push origin main
git push origin v1.1.0

これにより、次の処理が行われます。

• タグのバージョンが pyproject.toml と一致することを確認します
• パッケージをビルドします
• 自動生成されたリリースノートを含む GitHub リリースを作成します
• PyPI に自動的に公開します

オプション 2：手動リリース

GitHub の UI から手動でリリースを作成し、その後、必要に応じて公開します。

1. GitHub の Releases に移動します
2. 「Draft a new release」をクリックします
3. 新しいタグを作成するか、既存のタグを選択します
4. リリースの詳細を入力します
5. 「Publish release」をクリックします

リリースを公開すると、ワークフローによって PyPI に自動的に公開されます。公開を遅らせるために、ドラフトリリースを作成することもできます。

API 設計の理念

MCP Server Whisper は、MCP クライアントに最適化された、フラットで型安全な API 設計を採用しています。

• フラットな引数：よりシンプルで直感的な呼び出しを実現するため、すべてのツールはネストされたオブジェクトではなく、フラットなパラメーターを受け取ります
• 型安全なレスポンス：すべてのツールは、型が厳密に定義された Pydantic モデル（TranscriptionResult、ChatResult、AudioProcessingResult、TTSResult）を返します
• 単一アイテム操作：1 回の呼び出しで 1 つのファイルを処理し、並列処理は MCP プロトコルがネイティブに処理します
• ファイルごとのエラー処理：失敗はバッチ全体ではなく、個々の操作に限定されます
• 自己文書化：型ヒントにより、IDE や AI モデルで自動補完と検証が可能になります

この設計により、AI アシスタントがツールを正しく使用し、結果を確実に処理することが大幅に容易になります。

仕組み

アーキテクチャの詳細については、アーキテクチャのドキュメントを参照してください。

MCP Server Whisper は Model Context Protocol を基盤としており、AI モデルが外部のツールやデータソースとやり取りする方法を標準化しています。このサーバーは次の機能を提供します。

1. 音声処理機能の公開：フラットで型安全な API を備えた、標準化された MCP ツールインターフェースを通じて提供します
2. 並列処理の実装：anyio の構造化された並行処理を使用し、MCP クライアントが並列処理をネイティブに扱います
3. ファイル操作の管理：検出、検証、変換、圧縮を処理します
4. 高機能な文字起こしの提供：さまざまな OpenAI モデルと拡張テンプレートを利用します
5. パフォーマンスの最適化：繰り返しの操作にキャッシュ機構を使用します
6. 型安全性の確保：すべてのレスポンスで Pydantic モデルを使用し、検証と IDE のサポートを実現します

内部では、次のものを使用しています。

• 音声ファイルの操作に pydub（Python 3.13 以降では audioop-lts）を使用
• 構造化された並行処理とタスクグループの管理に anyio を使用
• 並列タスクグループから結果を収集するために aioresult を使用
• OpenAI の最新の文字起こしモデル（gpt-4o-transcribe を含む）
• 理解を強化するための OpenAI の GPT-4o 音声モデル
• 高品質な音声合成のための OpenAI の gpt-4o-mini-tts
• MCP サーバーの実装を簡素化する FastMCP
• コードベース全体での型ヒントと厳格な mypy 検証

貢献

皆さまからの貢献を歓迎します！以下の手順に従ってください。

1. リポジトリをフォークします
2. 機能用の新しいブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更を加えます
4. テストとリンティングを実行します（uv run pytest && uv run ruff check src && uv run mypy --strict src）
5. 変更をコミットします（git commit -m 'Add some amazing feature'）
6. ブランチにプッシュします（git push origin feature/amazing-feature）
7. プルリクエストを作成します

ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細については、LICENSEファイルを参照してください。

謝辞

• Model Context Protocol (MCP) - プロトコル仕様の提供
• pydub - 音声処理の提供
• OpenAI Whisper - 音声文字起こしの提供
• FastMCP - MCP サーバー実装の提供
• Anthropic Claude - 自然言語での対話の提供
• MCP Review - このMCPサーバーはMCP Reviewの認定を受けています