typecast-api

This MCP server implements a Model Context Protocol service for the Typecast API, enabling MCP clients to interact with Typecast's model endpoints in a standardized way. It supports two models: ssfm-v30 (the latest model with Preset + Smart Mode and broad language coverage) and ssfm-v21 (stable production model with Preset Mode only). Common tasks include retrieving available voices, converting text to speech, playing generated audio, and controlling voice/preset behaviors through the Context Protocol interface. You can leverage the Smart Mode to have the server infer emotion from context (previous_text and next_text) for smoother, context-aware speech output, or choose Preset Mode for explicit emotion control across the supported presets such as normal, happy, sad, angry, whisper, toneup, and tonedown.

To use the server with Claude Desktop or Cursor, configure your MCP settings to point to this server using uvx or your preferred invocation method. The environment variables TYPECAST_API_KEY and TYPECAST_OUTPUT_DIR are required to authenticate with Typecast API and designate where outputs should be stored. The server exposes endpoints aligned with the MCP contract so clients can request voice generation, fetch voice options, and manage playback in a consistent way across tools.

Prerequisites:

• Python 3.10 or higher (and optionally uv/uvx for package management)
• Git (for clone method, optional)
• Network access to fetch dependencies from PyPI or Git repositories

Option A: Using uvx (no manual installation required)

1. Ensure uvx is installed in your environment.
2. Run the server directly from GitHub:

uvx --from git+https://github.com/neosapience/typecast-api-mcp-server.git typecast-api-mcp-server

3. Provide required environment variables when launching (example):

ENV TYPECAST_API_KEY=YOUR_API_KEY
ENV TYPECAST_OUTPUT_DIR=/path/to/output

Option B: Local installation (clone and run)

1. Clone the repository and navigate into it:

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

2. Install dependencies (Python 3.10+ required):

uv venv
uv pip install -e .

3. Run the server locally:

uv run python app/main.py

4. Configure your MCP client to point to the local server as shown in the README examples, including the necessary environment variables.

Environment variables:

• TYPECAST_API_KEY: Your Typecast API key.
• TYPECAST_OUTPUT_DIR: Directory where generated audio/outputs will be stored (default can be ~/Downloads/typecast_output).
• On Linux, you may need to set XDG_RUNTIME_DIR=/run/user/$(id -u) if running in environments without a standard runtime directory.

Configuration tips:

• When using uvx from GitHub, you can pass the URL and the package name as shown in the examples to avoid manual cloning.
• Ensure your output directory exists and is writable by the process running the MCP server.
• If you switch models (ssfm-v30 vs ssfm-v21), confirm the server supports the desired features (e.g., Smart Mode for emotion inference in ssfm-v30).

Common issues:

• Missing API key or invalid endpoint errors: double-check TYPECAST_API_KEY and network access.
• Permission errors writing to TYPECAST_OUTPUT_DIR: verify filesystem permissions.
• Linux runtime issues: set XDG_RUNTIME_DIR if required by your environment.