Skip to main content
Glama
Sign In
deenesjakoruzh
gpu-transcription-mcp

gpu-transcription-mcp

by ollayf
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

GPU Queue

組み込みのジョブキューを備えた、faster-whisperベースの文字泸こしサービスです。複数のエージェントが同一の GPU を競合なく共有できます。キュュー/ワーカー/エンジンの中核部はトランスポート非依存であり、互換可能な 2 つのサーバー を介して公開されます。クライアントが対応している方を選んでください:

サーバー

エントリポイント

デフォルトポー

クライアント

MCP

server.py

8000

MCP 対応エージェント (FastMCP)

Flask

ask_server.py

801

任意の HTTP/JSON クライアント

どちらも同じ QueueManager をラップしているため、ジョブは引き続き 1 つずつ処理され、レスポンスのペイロードも同一です (共通の app/service.py を使用)。

しくみ

submit  ─►  ┌──────────────┐   one worker, one GPU   ┌───────────────┐
            │  job queue   │ ──────────────────────► │ WhisperEngine │
poll    ◄─  └──────────────┘   processed serially     └───────────────┘

ジョブをキューに投入すると、即座に job_id が返ります。その後、ステータスが done (または error) になるまでポーリングします。単一つのワーカーがキューを 1 ジョブずつ処理していくため、共有 GPU 上で 2 つの文字起こしが同時に実行されることはありません。

Related MCP server: faster-whisper-mcp

インストール

pip install -e .        # or: uv sync

このインストールにより、fastmcp (MCP トランスポート)、flask + waitress (HHTP トランスポート)、および faster-whisper (エンジン) が取り込まれます。

サーバーの起動

1 つ のサーバーを選択してください。両者は独立しており、互いにインポートしません:

# MCP transport (streamable-http on :8000)
python server.py
python server.py --port 9000
python server.py --transport stdio        # for stdio MCP clients

# Flask transport (HTTP/JSON on :8001)
python flask_server.py
python flask_server.py --port 9001
python flask_server.py --debug            # Flask dev server with auto-reload

必す単一のプロセスだけで実行してください — キューとジョブの登録はメモリ上に保持されます。マルチスレッドは問題ありませんが (レイトレスはスレッド・プールを使います)、マルチワーカープロセスは不可です。それぞれが個別の、共有されないキューを持つことになるためです。

Flask サーバー (本番の waitress パスを含む) は、起動バナーを出力し、リクエストごとーロ 1 行を標準出力にログします (例: GET /queue -> 200 (1.2ms))。

エンジンの設定 (両サーバー共通)

環境変数から読み取ります:

  • WHISPER_MODEL (デフォルト: distil-large-v3.5)

  • WHISPER_DEVICE (デフォルト: auto)

  • WHISPER_COMPUTE_TYP (デフォルト: auto)

  • WHISPER_MOL_DIR

HTTP API (Flask トランスポート)

メソッドとパス

説明

GET /health

ヘルスチェック → 正常なら 200 {"status":"ok","loop_running":true,"queue":{...}}。ワーカー・ループが停止している場合は 503

GET /ping

死活確認 → {"ok": true, "time": ...}

POST /transcriptions

ジョブの投入: {"audio_path": "...", "args": "--format text"} → job_id と position を含む 202

GET /transcriptions/<id>

ステータスをポーリング。status が done のときは output が含まれ、不明なジョブなら 404

POST /transcriptions/<job_id>/cancel

キュー待ち・実行中のジョブをキャレース

GET /queue

実行中のジョブ、キュー待ちのジョブ、完了件数

例セッション:

curl localhost:8001/ping

# submit
curl -X POST localhost:8001/transcriptions \
  -H 'Content-Type: application/json' \
  -d '{"audio_path":"/abs/path/audio.mp3","args":"--format text"}'
# → {"job_id":"j_ab12cd34","position":1, ...}

# poll until "status":"done"
curl localhost:8001/transcriptions/j_ab12cd34

# inspect the queue / cancel
curl localhost:8001/queue
curl -X POST localhost:8001/transcriptions/j_ab12cd34/cancel

MCP API (MCP トランスポート)

同じ操作を、5 つの FastMCP ツールとして公開します:

ツール

説明

ping()

死活確認

submit_words(audio_path, args="")

ジョブをキューに投入し、job_id + position を返します

get_transcriptions_status(ob_id)

ジョブをポーリング。完了すると output が設定されます

cancel_ob(ob_id)

キュー待ち・実行中のジョブをキャンセル

queue_status()

実行中ジョブ・キュー待ちのジョブ・完了件数

起動中の MCP サーバーへのクイック確認 (fastmcp クライアント使用):

python test_ping.py                       # ping the server
python test_live.py --audio /path/audio.mp3   # full submit → poll → print transcript

args フラグ (両トランスポート共通)

args 文字列は、どちらのトランスポートでも同じ faster-whisper CLI フラグを受け付けられます (例: --format srt、--model large-v3、--anzuage en、--zh) --arize、--word-timestamps、--beam-size 5)。なお一覧は app/queue_manager.py の _ARG_MAP を参照してください。

📖 HTTP リファレンス完全版: リクエスト/レスポンスのスキーマ、ステータスコーダ、ジョブのラフサイクル、args フラグについては、docs/HTTP_API.md を参照。

プロジェクト構成

app/
  queue_manager.py   queue, worker, engine lifecycle, CLI-arg → kwargs bridge
  whisper/engine.py  faster-whisper wrapper (model stays loaded between jobs)
  models.py          JobRecord dataclass
  service.py         payload-shaping shared by both transports
  main.py / tools.py MCP transport (create_mcp_app + tool definitions)
  flask_app.py       Flask transport (create_flask_app + routes)
server.py            run the MCP server      (:8000)
flask_server.py      run the Flask server    (:8001)

Docker

同梶の Dockerile / docker-compose.yml は、NVIDIA GPU の予約付きで MCP サーバー (CMD ["python", "server.py"]、ポート 8000) を起動します。代わりにコンテナ内で Flask トランスポートを動かすには、起動コマンドを上書きしてください (例):

command: python flask_server.py --port 8000

テスト

pytest -m "not integration"   # unit tests (engine mocked) — covers core, MCP, and Flask
pytest -m integration         # requires faster-whisper + a real model/audio file

  • tests/test_queue_manager.py — キュー / ワーカー / キャンセルのロジック

  • tests/test_service.py — 共通のペイロード整形

  • tests/test_tools.py — MCP トランスポートのエンドツーエンド (エンジンはモック)

  • tests/test_flask_app.py — テストクライアントを使った Flask ルートのエンドツーエンド

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityStale
ResponsivenessNo recent community issues

Resources

Related MCP Connectors

Related MCP Servers

  • faster-whisper-mcp

    uzusio
    F
    license
    A
    quality
    D
    maintenance
    Enables high-quality transcription and subtitle generation from local media files or URLs using Faster Whisper on local hardware. It supports automatic language detection and integration with MCP clients for seamless speech-to-text workflows.
    3
    -

  • Whisper MCP Server

    jwulff
    A
    license
    A
    quality
    B
    maintenance
    Provides local audio transcription using whisper.cpp, supporting multiple models and audio formats. Enables transcription of audio files via MCP tools with optional timestamps.
    3
    94 npm
    3
    MIT

  • EarSay MCP

    AlastorMordrek
    A
    license
    A
    quality
    D
    maintenance
    Provides voice transcription control and polling for MCP-compatible agents, enabling start/stop/pause/resume and retrieval of new text via tools.
    8
    MIT