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

> 타입캐스트 TTS를 Claude, Cursor 및 기타 MCP 호환 클라이언트와 통합하세요.

<Info>
  이 [Model Context Protocol](https://modelcontextprotocol.io/docs/getting-started/intro)을 연결하여 AI에게 완전한 타입캐스트 지식을 제공하고, 타입캐스트 TTS를 서비스에 몇 분 만에 통합하세요.
</Info>

## 원클릭 설치

Cursor와 Replit의 경우 아래 버튼을 클릭하세요:

<CardGroup cols={2}>
  <Card title="Cursor에 추가" icon="download" href="https://cursor.com/en-US/install-mcp?name=typecast-helper&config=eyJ1cmwiOiJodHRwczovL3R5cGVjYXN0LmFpL2RvY3MvbWNwIn0%3D">
    Cursor IDE용 원클릭 설치
  </Card>

  <Card title="Replit에 추가" icon="download" href="https://replit.com/integrations?mcp=eyJkaXNwbGF5TmFtZSI6IlR5cGVjYXN0IiwiYmFzZVVybCI6Imh0dHBzOi8vdHlwZWNhc3QuYWkvZG9jcy9tY3AifQ==">
    Replit용 원클릭 설치
  </Card>
</CardGroup>

### 기타 MCP 클라이언트

다른 MCP 호환 클라이언트의 경우 이 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. Windsurf 설정 열기
  2. **Cascade** → **MCP Servers**로 이동
  3. **"Add Server"** → **"Add Remote MCP Server"** 클릭
  4. URL 입력: `https://typecast.ai/docs/mcp`
</Accordion>

<Accordion title="VS Code (Copilot)">
  `.vscode/mcp.json`에 추가하세요:

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

이제 AI 어시스턴트에게 타입캐스트 TTS를 프로젝트에 통합하는 것을 도와달라고 요청할 수 있습니다.

### 활용 방법

연결되면 AI 어시스턴트가 다음에 대한 지식을 얻습니다:

* **API 통합** — 모든 언어에 대한 코드 예제 얻기
* **보이스 선택** — 용도에 맞는 완벽한 보이스 찾기
* **모범 사례** — 다양한 시나리오에 대한 최적의 설정 배우기
* **문제 해결** — 일반적인 문제에 대한 빠른 해결책

<CodeGroup>
  ```plaintext 예시: 빠른 통합 theme={null}
  "내 프로젝트에 Typecast TTS를 통합해줘."
  ```
</CodeGroup>

***

<Note>
  위 설정이 필요한 전부입니다. 아래 섹션은 고급 사용 사례를 위한 선택 사항입니다.
</Note>

***

## 고급: 자동 TTS 생성

자동으로 오디오 파일을 생성해야 하나요? 타입캐스트 자체 호스팅 MCP 서버를 사용하면 AI 어시스턴트가 **타입캐스트 API를 직접 호출**하여 필요에 따라 오디오를 생성할 수 있습니다. 배치 처리 및 자동화 워크플로우에 완벽합니다.

자체 호스팅 서버는 자연어 설명으로 음성을 찾는 `recommend_voices`도 제공합니다. 추천 결과에는 `voice_id`, `voice_name`, `score`만 포함되므로, 지원 모델, 감정, 성별, 나이대, 사용 사례 같은 메타데이터가 필요하면 `get_voice` 또는 `get_voices`를 함께 호출하세요.

### 차별점

| URL 기반 MCP     | 자체 호스팅 MCP 서버    |
| -------------- | ---------------- |
| 지식 및 가이드 제공    | 실제로 오디오 파일 생성    |
| API 호출 없음      | 타입캐스트 API를 직접 호출 |
| 학습 및 통합 도움에 좋음 | 자동화 및 배치 작업에 좋음  |

### 사전 준비 사항

* [uv](https://docs.astral.sh/uv/) 패키지 매니저
* 타입캐스트 API 키 ([여기서 받기](https://typecast.ai/developers/api/))

### 설정

<Tabs>
  <Tab title="Claude Desktop (macOS)">
    `~/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)">
    `%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)">
    `~/.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에서는 오디오 재생을 위해 `XDG_RUNTIME_DIR`이 필요합니다.
    </Note>
  </Tab>

  <Tab title="Cursor">
    Cursor의 MCP 설정에 추가하세요:

    ```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}
    # Typecast MCP 서버 추가
    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>

### 문제 해결

<AccordionGroup>
  <Accordion title="MCP 서버가 나타나지 않음">
    * 구성이 올바른지 확인하세요
    * 애플리케이션을 완전히 다시 시작하세요
    * `uv`가 설치되어 있고 PATH에서 사용 가능한지 확인하세요
  </Accordion>

  <Accordion title="API 키 오류">
    * API 키가 구성에 올바르게 설정되어 있는지 확인하세요
    * [타입캐스트 API](https://typecast.ai/developers/api/)에서 키를 확인하세요
  </Accordion>

  <Accordion title="오디오가 재생되지 않음 (Linux)">
    * `XDG_RUNTIME_DIR` 환경 변수를 설정하세요
    * 오디오 장치 확인: `aplay -l`
  </Accordion>
</AccordionGroup>

***

## 참고 자료

<CardGroup cols={2}>
  <Card title="GitHub 저장소" icon="github" href="https://github.com/neosapience/typecast-api-mcp-server">
    자체 호스팅 MCP 서버 소스 코드 보기
  </Card>

  <Card title="API 레퍼런스" icon="code" href="/ko/api-reference/text-to-speech/text-to-speech">
    타입캐스트 API 탐색하기
  </Card>

  <Card title="보이스 라이브러리" icon="microphone" href="https://typecast.ai/developers/api/voices">
    사용 가능한 음성 둘러보기
  </Card>

  <Card title="Python SDK" icon="python" href="/ko/sdk/python">
    사용자 정의 통합 구축하기
  </Card>
</CardGroup>