Typecast API

You set up an MCP server that exposes the Typecast API through the Model Context Protocol, enabling MCP clients to interact with Typecast API in a standardized way. This server supports voice management actions like listing voices, converting text to speech, and playing audio.

How to use

Use this MCP server with your MCP client to manage voices and produce audio through the Typecast API. You can connect the client to the server over the MCP protocol, then trigger actions such as listing available voices, generating speech from text, and playing the resulting audio in compatible environments.

How to install

Prerequisites: you need Python 3.10 or higher and the uv tooling for package management.

# Clone the project repository
git clone https://github.com/hyunseung/typecast-api-mcp-server-sample.git
cd typecast-api-mcp-server-sample

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

Environment preparation

Set the following environment variables to configure the server with your Typecast API access and output location.

TYPECAST_API_HOST=https://api.typecast.ai
TYPECAST_API_KEY=<your-api-key>
TYPECAST_OUTPUT_DIR=<your-output-directory> # default: ~/Downloads/typecast_output

Usage with Claude Desktop

You can run the MCP server via the Claude Desktop configuration by starting the process through uv and pointing to your project directory. The runtime uses the environment variables above to connect to the Typecast API and determine where to place generated outputs.

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

Manual execution

You can also start the server directly from the command line if you prefer to bypass the config file.

uv run python app/main.py

Available tools

get_voices

Retrieve the list of available voices from the MCP server using the V2 API.

get_voice

Fetch detailed information for a specific voice using the V2 API.

text_to_speech

Convert input text to spoken audio using the selected voice and presets.

play_audio

Play generated audio or route it to an output stream.

preset_mode

Apply preset emotion settings (for example, normal, happy, sad, angry, whisper, toneup, tonedown) on the ssfm-v30 model.

smart_mode

Automatically infer emotion from context using previous_text and next_text to tailor speech.