> ## Documentation Index
> Fetch the complete documentation index at: https://typecast.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP

<Info>
  Connect this [Model Context Protocol](https://modelcontextprotocol.io/docs/getting-started/intro) to give your AI complete Typecast knowledge, integrate Typecast TTS into your service in minutes.
</Info>

## One-Click Install

For Cursor and Replit, just click the button below:

<CardGroup cols={2}>
  <Card
    title="Add to Cursor"
    icon="download"
    href="https://cursor.com/en-US/install-mcp?name=typecast-helper&config=eyJ1cmwiOiJodHRwczovL3R5cGVjYXN0LmFpL2RvY3MvbWNwIn0%3D"
  >
    One-click install for Cursor IDE
  </Card>
  <Card
    title="Add to Replit"
    icon="download"
    href="https://replit.com/integrations?mcp=eyJkaXNwbGF5TmFtZSI6IlR5cGVjYXN0IiwiYmFzZVVybCI6Imh0dHBzOi8vdHlwZWNhc3QuYWkvZG9jcy9tY3AifQ=="
  >
    One-click install for Replit
  </Card>
</CardGroup>

### Other MCP Clients

For other MCP-compatible clients, add this URL:

```
https://typecast.ai/docs/mcp
```

<Accordion title="Claude Code">
  ```bash
  claude mcp add --transport http typecast-helper https://typecast.ai/docs/mcp
  ```
</Accordion>

<Accordion title="Windsurf">
  1. Open Windsurf Settings
  2. Navigate to **Cascade** → **MCP Servers**
  3. Click **"Add Server"** → **"Add Remote MCP Server"**
  4. Enter URL: `https://typecast.ai/docs/mcp`
</Accordion>

<Accordion title="VS Code (Copilot)">
  Add to your `.vscode/mcp.json`:

  ```json
  {
    "servers": {
      "typecast-helper": {
        "url": "https://typecast.ai/docs/mcp"
      }
    }
  }
  ```
</Accordion>

That's it! You can now ask your AI assistant to help you integrate Typecast TTS into your projects.

### What You Can Do

Once connected, your AI assistant gains knowledge about:

- **API Integration** - Get code examples for any language
- **Voice Selection** - Find the perfect voice for your use case
- **Best Practices** - Learn optimal settings for different scenarios
- **Troubleshooting** - Quick solutions for common issues

<CodeGroup>

```plaintext Example: Quick Integration
"Integrate Typecast TTS into my project."
```


</CodeGroup>

---

<Note>
  The setup above is all you need. The section below is optional for advanced use cases.
</Note>

---

## Advanced: Automated TTS Generation

Need to generate audio files automatically? The hosted or self-hosted Typecast API MCP server lets your AI assistant **directly call the Typecast API** to create audio on demand, perfect for batch processing and automated workflows.

Both options also provide `recommend_voices` for natural-language voice search. Recommendation results contain only `voice_id`, `voice_name`, and `score`, so call `get_voice` or `get_voices` when your workflow needs metadata such as supported models, emotions, gender, age, or use cases.

### What Makes This Different

| Docs MCP | Hosted API MCP | Self-hosted API MCP |
|----------|----------------|---------------------|
| Provides knowledge and guidance | Calls Typecast API directly | Calls Typecast API directly |
| No API key required | No local installation | Runs on your computer |
| Best for integration help | Best for quick automation | Best for local files and audio playback |

### Prerequisites

- Typecast API key ([Get yours here](https://studio.typecast.ai/developers/api/))
- [uv](https://docs.astral.sh/uv/) package manager (self-hosted only)

### Setup

<Tabs>
  <Tab title="Hosted Server">
    Add the hosted Streamable HTTP endpoint to an MCP client that supports custom headers:

    ```json
    {
      "mcpServers": {
        "typecast": {
          "url": "https://typecast.ai/docs/mcp",
          "headers": {
            "X-API-KEY": "YOUR_API_KEY"
          }
        }
      }
    }
    ```

    Without the API key, the hosted server exposes only `search_documentation`. Authenticated requests unlock the Typecast API tools. Generated audio is returned as a private download URL that expires after one hour.

    <Note>
      `play_audio` is available only when self-hosting. For hosted voice cloning, send `audio_base64` and an `.mp3` or `.wav` `audio_filename`.
    </Note>
  </Tab>
  <Tab title="Claude Desktop (macOS)">
    Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

    ```json
    {
      "mcpServers": {
        "typecast": {
          "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": "/Users/yourname/Downloads/typecast_output"
          }
        }
      }
    }
    ```
  </Tab>
  <Tab title="Claude Desktop (Windows)">
    Edit `%APPDATA%\Claude\claude_desktop_config.json`:

    ```json
    {
      "mcpServers": {
        "typecast": {
          "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": "C:\\Users\\yourname\\Downloads\\typecast_output"
          }
        }
      }
    }
    ```
  </Tab>
  <Tab title="Claude Desktop (Linux)">
    Edit `~/.config/Claude/claude_desktop_config.json`:

    ```json
    {
      "mcpServers": {
        "typecast": {
          "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": "/home/yourname/Downloads/typecast_output",
            "XDG_RUNTIME_DIR": "/run/user/1000"
          }
        }
      }
    }
    ```

    <Note>
      Linux requires `XDG_RUNTIME_DIR` for audio playback.
    </Note>
  </Tab>
  <Tab title="Cursor">
    Add to your MCP settings in Cursor:

    ```json
    {
      "mcpServers": {
        "typecast": {
          "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/output"
          }
        }
      }
    }
    ```
  </Tab>
  <Tab title="Claude Code">
    ```bash
    # Add the Typecast MCP server
    claude mcp add --transport stdio \
      --env TYPECAST_API_KEY=YOUR_API_KEY \
      --env TYPECAST_OUTPUT_DIR=/path/to/output \
      typecast -- uvx --from git+https://github.com/neosapience/typecast-api-mcp-server.git typecast-api-mcp-server
    ```
  </Tab>
</Tabs>

### Troubleshooting

<AccordionGroup>
  <Accordion title="MCP server not appearing">
    - Verify the configuration is correct
    - Restart your application completely
    - Check that `uv` is installed and available in your PATH
  </Accordion>
  <Accordion title="API key errors">
    - Confirm your API key is set correctly in the config
    - Verify your key at [Typecast API](https://studio.typecast.ai/developers/api/)
  </Accordion>
  <Accordion title="Audio not playing (Linux)">
    - Set `XDG_RUNTIME_DIR` environment variable
    - Check audio device: `aplay -l`
  </Accordion>
</AccordionGroup>

---

## Resources

<CardGroup cols={2}>
  <Card
    title="GitHub Repository"
    icon="github"
    href="https://github.com/neosapience/typecast-api-mcp-server"
  >
    View source code for Self-hosted MCP Server
  </Card>
  <Card
    title="API Reference"
    icon="code"
    href="/api-reference"
  >
    Explore the Typecast API
  </Card>
  <Card title="Voice Library" icon="microphone" href="https://studio.typecast.ai/developers/api/voices">
    Browse available voices
  </Card>
  <Card title="Python SDK" icon="python" href="/sdk/python">
    Build custom integrations
  </Card>
</CardGroup>