typecast-api-mcp-server

MCP Server for typecast-api, enabling seamless integration with MCP clients. This project provides a standardized way to interact with Typecast API through the Model Context Protocol.

About

This project implements a Model Context Protocol server for Typecast API, allowing MCP clients to interact with the Typecast API in a standardized way.

Supported Models

ssfm-v30 Features

• 7 Emotion Presets: normal, happy, sad, angry, whisper, toneup, tonedown
• Smart Mode: AI automatically infers emotion from context using `previous_text` and `next_text`
• 37 Languages: Extended language support

Feature Implementation Status

Quick Voice Cloning

The MCP server exposes tools for the current Custom Voice API:

• `clone_voice`: creates a quick-cloned custom voice from a local WAV or MP3 file.
• `create_professional_voice`: starts a professional clone; poll its status before use.
• `get_custom_voices` and `get_custom_voice`: list voices or inspect clone status.
• `delete_cloned_voice`: deletes a cloned voice ID that starts with `uc_`.

Instant cloning constraints:

• Voice name must be 1-30 characters.
• Audio sample must be WAV or MP3.
• Audio sample must be 25 MB or smaller.
• Use `ssfm-v30` unless you have a specific compatibility reason.

Typical flow:

1. Run `clone_voice` with `name`, `audio_file_path`, and optional `model`.

2. Use the returned `next_step_voice_id` and `next_step_model` in `text_to_speech`, `text_to_speech_stream`, or `text_to_speech_with_timestamps`.

3. Run `delete_cloned_voice` when the temporary cloned voice is no longer needed.

Professional cloning returns `202 Accepted`. Poll `get_custom_voice` until its

status becomes `completed` or `failed`; completion can take up to two hours.

Voice Recommendations

Use `recommend_voices` when you know the desired style, mood, language, or use

case but do not know the exact voice ID yet. It calls

`GET /v1/voices/recommendations` and returns candidates sorted by score.

The recommendation response intentionally contains only `voice_id`,

`voice_name`, and `score`. If an agent needs details about a recommended voice,

call `get_voice` for each returned ID or `get_voices` for a broader filtered

list before using the ID in TTS.

Setup

Hosted Server

The hosted Streamable HTTP endpoint is:

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

Without authentication, the server exposes only `search_documentation`. Send a

Typecast API key on every MCP request to unlock the Typecast API tools:

X-API-KEY: YOUR_TYPECAST_API_KEY

`Authorization: Bearer YOUR_TYPECAST_API_KEY` is also supported. The hosted

server does not store the key. Generated audio is returned as a private,

unguessable download URL that expires after one hour. `play_audio` remains a

local-only tool because a hosted server cannot play sound on the MCP client's

device.

To preserve how Typecast integration code was created, hosted clients may send

both attribution headers together:

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

Use `api-page` for API page onboarding and `api-docs` for API documentation

onboarding. The legacy `llms` and `skill` values remain accepted.

`X-Typecast-Generated-By` accepts a lowercase ASCII token up to 32 characters.

The server keeps its own `typecast-mcp/` User-Agent and appends this

attribution instead of replacing it.

On the hosted server, `clone_voice` accepts only `audio_base64` together with

an `audio_filename` ending in `.wav` or `.mp3`. `audio_file_path` is available

only when this MCP server runs locally.

Environment Variables

Set the following environment variables:

TYPECAST_API_KEY=
TYPECAST_OUTPUT_DIR= # default: ~/Downloads/typecast_output
TYPECAST_INTEGRATION_SOURCE= # optional; set both attribution variables
TYPECAST_GENERATED_BY=                     # optional; e.g. codex or claude-code

Usage with Claude Desktop / Cursor

You can add the following to your `claude_desktop_config.json` or Cursor MCP settings:

Recommended: Using uvx (No installation required)

{
  "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"
      }
    }
  }
}

This method automatically fetches and runs the server from GitHub without manual cloning.

Note for Linux users: If you're running on Linux, you need to add the `XDG_RUNTIME_DIR` environment variable to the `env` section:

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

Alternative: Local Installation

If you prefer to clone and run locally:

Git Clone

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

Dependencies

This project requires Python 3.10 or higher and uses `uv` for package management.

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

Local Configuration

{
  "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"
      }
    }
  }
}

Replace `/PATH/TO/YOUR/PROJECT` with the actual path where your project is located.

Manual Execution

You can also run the server manually:

uv run python app/main.py

Contributing

Contributions are always welcome! Feel free to submit a Pull Request.

License

MIT License