> ## 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

> Integrate Typecast TTS with Claude, Cursor, and other MCP-compatible clients.

<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 theme={null}
  claude mcp add 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 theme={null}
  {
    "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 theme={null}
  "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 Typecast Self-hosted MCP Server lets your AI assistant **directly call the Typecast API** to create audio on demand, perfect for batch processing and automated workflows.

### What Makes This Different

| URL-based MCP                         | Self-hosted MCP Server            |
| ------------------------------------- | --------------------------------- |
| Provides knowledge & guidance         | Actually generates audio files    |
| No API calls made                     | Calls Typecast API directly       |
| Great for learning & integration help | Great for automation & batch work |

### Prerequisites

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

### Setup

<Tabs>
  <Tab title="Claude Desktop (macOS)">
    Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

    ```json theme={null}
    {
      "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 theme={null}
    {
      "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 theme={null}
    {
      "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 theme={null}
    {
      "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 theme={null}
    # Add the Typecast MCP server
    claude mcp add typecast \
      --command "uvx --from git+https://github.com/neosapience/typecast-api-mcp-server.git typecast-api-mcp-server" \
      --env TYPECAST_API_KEY=YOUR_API_KEY \
      --env TYPECAST_OUTPUT_DIR=/path/to/output
    ```
  </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://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://typecast.ai/developers/api/voices">
    Browse available voices
  </Card>

  <Card title="Python SDK" icon="python" href="/sdk/python">
    Build custom integrations
  </Card>
</CardGroup>