typecast-api-mcp-server-sample

typecast-api-mcp-server

typecast-api 用の MCP サーバーです。MCP クライアントとシームレスに連携できます。このプロジェクトは、Model Context Protocol を通じて Typecast API を利用するための標準化された方法を提供します。

概要

このプロジェクトは、Typecast API 用の Model Context Protocol サーバーを実装し、MCP クライアントが標準化された方法で Typecast API を利用できるようにします。

対応モデル

モデル	説明	感情の制御
ssfm-v30	最新モデル（推奨）	プリセット＋スマートモード
ssfm-v21	安定した本番環境向けモデル	プリセットのみ

ssfm-v30 の機能

• 7 種類の感情プリセット：normal、happy、sad、angry、whisper、toneup、tonedown
• スマートモード：previous_text と next_text を使用し、AI が文脈から感情を自動的に推測します
• 37 言語：拡張された言語サポート

機能の実装状況

機能	状況
音声管理
ドキュメントの検索	✅
音声の取得（V3 API）	✅
音声の取得 use_cases フィルター	✅
音声の取得（V3 API）	✅
音声の推薦	✅
テキスト読み上げ	✅
テキスト読み上げ（ストリーミング）	✅
テキスト読み上げ（タイムスタンプ付き）	✅
サブスクリプション情報の取得	✅
音声の再生	✅
出力制御
target_lufs 音量正規化	✅
ssfm-v30 のサポート
プリセットモード	✅
スマートモード	✅
カスタム音声
インスタント／プロフェッショナルクローン	✅
カスタム音声の一覧表示／取得／削除	✅

音声のクイッククローン

MCP サーバーは、現在の Custom Voice API 用のツールを提供します。

• clone_voice：ローカルの WAV または MP3 ファイルから、カスタム音声をクイッククローンします。
• create_professional_voice：プロフェッショナルクローンを開始します。使用する前にステータスを確認してください。
• get_custom_voices と get_custom_voice：音声の一覧表示、またはクローンのステータス確認を行います。
• delete_cloned_voice：uc_ で始まるクローン音声 ID を削除します。

インスタントクローンの制約：

• 音声名は 1～30 文字である必要があります。
• 音声サンプルは WAV または MP3 である必要があります。
• 音声サンプルのサイズは 25 MB 以下である必要があります。
• 特別な互換性上の理由がない限り、ssfm-v30 を使用してください。

一般的な手順：

1. name、audio_file_path、および任意の model を指定して clone_voice を実行します。
2. 返された next_step_voice_id と next_step_model を text_to_speech、text_to_speech_stream、または text_to_speech_with_timestamps で使用します。
3. 一時的なクローン音声が不要になったら、delete_cloned_voice を実行します。

プロフェッショナルクローンは 202 Accepted を返します。ステータスが completed または failed になるまで get_custom_voice で確認してください。完了まで最大 2 時間かかることがあります。

音声の推薦

希望するスタイル、雰囲気、言語、または用途は分かっているものの、正確な音声 ID が分からない場合は、recommend_voices を使用してください。このツールは GET /v1/voices/recommendations を呼び出し、スコア順に並べた候補を返します。

推薦結果に含まれるのは、意図的に voice_id、 voice_name、および score のみです。エージェントが推薦された音声の詳細を必要とする場合は、返された各 ID に対して get_voice を呼び出すか、ID を TTS で使用する前に get_voices でより広範囲の条件付き一覧を取得してください。

セットアップ

ホステッドサーバー

ホステッド Streamable HTTP エンドポイントは次のとおりです。

https://typecast-api-docs-web-production.up.railway.app/mcp

認証なしの場合、サーバーが公開するのは search_documentation のみです。Typecast API ツールを利用するには、すべての MCP リクエストに Typecast API キーを含めてください。

X-API-KEY: YOUR_TYPECAST_API_KEY

Authorization: Bearer YOUR_TYPECAST_API_KEY もサポートされています。ホステッドサーバーはキーを保存しません。生成された音声は、推測できない非公開のダウンロード URL として返され、1 時間後に有効期限が切れます。ホステッドサーバーでは MCP クライアントのデバイス上で音声を再生できないため、play_audio は引き続きローカル専用のツールです。

Typecast 統合コードがどのように作成されたかを保持するため、ホステッドクライアントは次の 2 つの帰属情報ヘッダーを同時に送信できます。

X-Typecast-Integration-Source: api-docs
X-Typecast-Generated-By: codex

API ページのオンボーディングには api-page を、API ドキュメントのオンボーディングには api-docs を使用してください。従来の llms と skill の値も引き続き使用できます。 X-Typecast-Generated-By で指定できるのは、32 文字以内の小文字 ASCII トークンです。サーバーは独自の typecast-mcp/<version> User-Agent を維持し、これを置き換えるのではなく、帰属情報を追加します。

ホステッドサーバーでは、clone_voice が受け付けるのは audio_filename が .wav または .mp3 で終わる audio_base64 のみです。audio_file_path は、この MCP サーバーをローカルで実行する場合にのみ使用できます。

環境変数

次の環境変数を設定します。

TYPECAST_API_KEY=<your-api-key>
TYPECAST_OUTPUT_DIR=<your-output-directory> # default: ~/Downloads/typecast_output
TYPECAST_INTEGRATION_SOURCE=<llms|skill|api-page|api-docs> # optional; set both attribution variables
TYPECAST_GENERATED_BY=<coding-agent-id>                     # optional; e.g. codex or claude-code

Claude Desktop / Cursor での使用方法

以下を claude_desktop_config.json または Cursor MCP 設定に追加できます。

推奨：uvx を使用（インストール不要）

{
  "mcpServers": {
    "typecast-api-mcp-server": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/neosapience/typecast-api-mcp-server.git",
        "typecast-api-mcp-server"
      ],
      "env": {
        "TYPECAST_API_KEY": "YOUR_API_KEY",
        "TYPECAST_OUTPUT_DIR": "PATH/TO/YOUR/OUTPUT/DIR"
      }
    }
  }
}

この方法では、手動でクローンせずに GitHub からサーバーを自動的に取得して実行します。

Linux ユーザーへの注意：Linux で実行する場合は、XDG_RUNTIME_DIR 環境変数を env セクションに追加する必要があります。

"env": {
  "TYPECAST_API_KEY": "YOUR_API_KEY",
  "TYPECAST_OUTPUT_DIR": "PATH/TO/YOUR/OUTPUT/DIR",
  "XDG_RUNTIME_DIR": "/run/user/1000"
}

代替方法：ローカルインストール

クローンしてローカルで実行する場合は、次の手順に従ってください。

Git クローン

git clone https://github.com/neosapience/typecast-api-mcp-server.git
cd typecast-api-mcp-server

依存関係

このプロジェクトには Python 3.10 以降が必要で、パッケージ管理には uv を使用します。

# Create virtual environment and install packages
uv venv
uv pip install -e .

ローカル設定

{
  "mcpServers": {
    "typecast-api-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/PATH/TO/YOUR/PROJECT",
        "run",
        "typecast-api-mcp-server"
      ],
      "env": {
        "TYPECAST_API_KEY": "YOUR_API_KEY",
        "TYPECAST_OUTPUT_DIR": "PATH/TO/YOUR/OUTPUT/DIR"
      }
    }
  }
}

/PATH/TO/YOUR/PROJECT を、プロジェクトが配置されている実際のパスに置き換えてください。

手動実行

サーバーを手動で実行することもできます。

uv run python app/main.py

コントリビューション

コントリビューションをいつでも歓迎します。お気軽にプルリクエストを送信してください。

ライセンス

MIT ライセンス