> ## 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>
  이 [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
  claude mcp add --transport http 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
  {
    "servers": {
      "typecast-helper": {
        "url": "https://typecast.ai/docs/mcp"
      }
    }
  }
  ```
</Accordion>

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

### 활용 방법

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

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

<CodeGroup>

```plaintext 예시: 빠른 통합
"내 프로젝트에 Typecast TTS를 통합해줘."
```


</CodeGroup>

---

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

---

## 고급: 자동 TTS 생성

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

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

### 차별점

| 문서 MCP | 호스팅 API MCP | 자체 호스팅 API MCP |
|----------|----------------|----------------------|
| 지식 및 가이드 제공 | 타입캐스트 API 직접 호출 | 타입캐스트 API 직접 호출 |
| API 키 불필요 | 로컬 설치 불필요 | 내 컴퓨터에서 실행 |
| 통합 도움에 적합 | 빠른 자동화에 적합 | 로컬 파일 및 오디오 재생에 적합 |

### 사전 준비 사항

- 타입캐스트 API 키 ([여기서 받기](https://studio.typecast.ai/developers/api/))
- [uv](https://docs.astral.sh/uv/) 패키지 매니저 (자체 호스팅만 해당)

### 설정

<Tabs>
  <Tab title="호스팅 서버">
    사용자 지정 헤더를 지원하는 MCP 클라이언트에 호스팅 Streamable HTTP 엔드포인트를 추가하세요:

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

    API 키가 없으면 호스팅 서버는 `search_documentation`만 제공합니다. 인증된 요청에서는 타입캐스트 API 도구를 모두 사용할 수 있습니다. 생성된 오디오는 한 시간 후 만료되는 비공개 다운로드 URL로 반환됩니다.

    <Note>
      `play_audio`는 자체 호스팅에서만 사용할 수 있습니다. 호스팅 서버에서 음성을 복제할 때는 `audio_base64`와 `.mp3` 또는 `.wav` 확장자의 `audio_filename`을 보내세요.
    </Note>
  </Tab>
  <Tab title="Claude Desktop (macOS)">
    `~/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)">
    `%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)">
    `~/.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에서는 오디오 재생을 위해 `XDG_RUNTIME_DIR`이 필요합니다.
    </Note>
  </Tab>
  <Tab title="Cursor">
    Cursor의 MCP 설정에 추가하세요:

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

### 문제 해결

<AccordionGroup>
  <Accordion title="MCP 서버가 나타나지 않음">
    - 구성이 올바른지 확인하세요
    - 애플리케이션을 완전히 다시 시작하세요
    - `uv`가 설치되어 있고 PATH에서 사용 가능한지 확인하세요
  </Accordion>
  <Accordion title="API 키 오류">
    - API 키가 구성에 올바르게 설정되어 있는지 확인하세요
    - [타입캐스트 API](https://studio.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://studio.typecast.ai/developers/api/voices">
    사용 가능한 음성 둘러보기
  </Card>
  <Card title="Python SDK" icon="python" href="/ko/sdk/python">
    사용자 정의 통합 구축하기
  </Card>
</CardGroup>