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

# Venice MCP 서버

> 공식 Venice Model Context Protocol 서버는 모든 MCP 호스트에서 채팅, 이미지, 비디오, 오디오, 음악, 캐릭터를 위한 31개의 Venice 도구를 노출합니다.

[Venice MCP 서버](https://github.com/veniceai/venice-mcp-server)는 Venice를 위한 공식 [Model Context Protocol](https://modelcontextprotocol.io/) 서버입니다. Venice API 전체(chat, image, video, audio, music, embeddings, web augment, characters)를 모든 MCP 호환 에이전트가 호출할 수 있는 **31개 도구**로 노출합니다.

<Card title="GitHub: veniceai/venice-mcp-server" icon="github" href="https://github.com/veniceai/venice-mcp-server">
  npm에는 [`@veniceai/mcp-server`](https://www.npmjs.com/package/@veniceai/mcp-server)로 게시되어 있습니다. MIT 라이선스.
</Card>

<CardGroup cols={3}>
  <Card title="31개 도구" icon="toolbox">
    하나의 설정 블록 안에 Venice의 모든 모달리티
  </Card>

  <Card title="모든 MCP 호스트" icon="plug">
    Claude Desktop, Cursor, ChatGPT, LM Studio, Continue 등
  </Card>

  <Card title="지갑 인증(선택)" icon="wallet">
    API 키를 가져오거나, x402로 SIWE 서명 지갑을 통해 호출당 결제
  </Card>
</CardGroup>

## 빠른 시작

<Steps>
  <Step title="Venice API 키 발급">
    [venice.ai/settings/api](https://venice.ai/settings/api)에서 키를 발급받으세요. 단계별 안내는 [API 키 가이드](/guides/getting-started/generating-api-key)를 참고하세요.
  </Step>

  <Step title="MCP 호스트 설정에 Venice 추가">
    MCP 호스트 설정 파일에 다음을 넣으세요:

    ```json theme={"system"}
    {
      "mcpServers": {
        "venice": {
          "command": "npx",
          "args": ["-y", "@veniceai/mcp-server@0.2.0"],
          "env": { "VENICE_API_KEY": "<your-venice-api-key>" }
        }
      }
    }
    ```

    흔한 설정 경로:

    | Host                     | Path                                                              |
    | ------------------------ | ----------------------------------------------------------------- |
    | Claude Desktop (macOS)   | `~/Library/Application Support/Claude/claude_desktop_config.json` |
    | Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json`                     |
    | Cursor                   | `~/.cursor/mcp.json`                                              |
    | LM Studio                | 앱의 MCP 설정에서 `mcp.json`                                            |
  </Step>

  <Step title="MCP 호스트 재시작">
    이제 에이전트가 chat, image, video, music, TTS, ASR 외 25개 이상의 Venice 도구를 사용할 수 있습니다.
  </Step>
</Steps>

<Note>
  대부분의 MCP 호스트는 `env` 블록에 **명시적으로 나열된** 환경 변수만 전달합니다. 시스템 수준 env vars는 상속되지 않습니다. API 키를 설정했는데 402 에러가 보인다면, 설정의 `env` 안에 `VENICE_API_KEY`가 있는지 다시 확인하세요.
</Note>

## 무엇을 얻나요

Venice의 모든 모달리티를 아우르는 **31개 도구**, **3개의 리소스**(`venice://models`, `venice://styles`, `venice://voices`), **3개의 prompt 템플릿**.

### Chat 및 임베딩

| Tool                         | Description                                        |
| ---------------------------- | -------------------------------------------------- |
| `venice_chat`                | Venice의 LLM 카탈로그 전체에 대한 OpenAI 호환 chat completion. |
| `venice_responses`           | 단일/멀티 턴 도구를 지원하는 OpenAI 호환 Responses API.          |
| `venice_embeddings`          | 텍스트 input에 대한 임베딩 계산.                              |
| `venice_chat_with_character` | slug로 Venice 캐릭터와 채팅.                              |

### 이미지

| Tool                      | Description                                                                        |
| ------------------------- | ---------------------------------------------------------------------------------- |
| `venice_image_generate`   | 이미지 생성(Flux 2, Lustify SDXL, Anime/WAI, Qwen Image, GPT Image, Nano Banana Pro 등). |
| `venice_image_edit`       | prompt로 이미지 편집.                                                                    |
| `venice_image_multi_edit` | 하나의 prompt로 여러 이미지를 함께 편집.                                                         |
| `venice_image_upscale`    | 이미지를 최대 4×까지 업스케일.                                                                 |
| `venice_image_remove_bg`  | 이미지 배경 제거.                                                                         |
| `venice_image_styles`     | 이미지 스타일 프리셋 목록.                                                                    |

### 비디오

| Tool                          | Description                                                                |
| ----------------------------- | -------------------------------------------------------------------------- |
| `venice_video_generate`       | 비디오 생성 큐 등록(Sora 2, Veo 3.1, Kling, Wan, LTX 2, Seedance, Runway Gen-4 등). |
| `venice_video_status`         | 큐에 등록된 비디오 작업 상태 확인.                                                       |
| `venice_video_complete`       | 완료된 비디오를 다운로드 완료로 표시. 서버 측 미디어 삭제.                                         |
| `venice_video_transcriptions` | YouTube 비디오 URL 전사.                                                        |
| `venice_video_quote`          | 큐 등록 전 가격 견적.                                                              |

### 오디오 (TTS / ASR)

| Tool                 | Description                      |
| -------------------- | -------------------------------- |
| `venice_tts`         | 클론 음성과 감정 태그를 갖춘 text-to-speech. |
| `venice_asr`         | URL에서 오디오 전사.                    |
| `venice_voice_clone` | 내장 음성 목록 또는 샘플로부터 음성 클론.         |
| `venice_audio_quote` | 음악 생성 가격 견적.                     |

### 음악

| Tool                    | Description                                                                                                                                |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `venice_music_generate` | 음악 생성 큐 등록(`ace-step-15`, `elevenlabs-music`, `minimax-music-v2/v25/v26`, `stable-audio-25`, `mmaudio-v2`, `elevenlabs-sound-effects-v2`). |
| `venice_music_status`   | 큐에 등록된 음악 작업 상태 확인.                                                                                                                        |
| `venice_music_complete` | 완료된 음악 작업을 다운로드 완료로 표시.                                                                                                                    |

### 웹 augment, 카탈로그, 크립토

| Tool                     | Description                                                    |
| ------------------------ | -------------------------------------------------------------- |
| `venice_web_search`      | 웹 검색(Firecrawl 기반).                                            |
| `venice_web_scrape`      | URL 하나를 마크다운으로 스크래핑.                                           |
| `venice_text_parser`     | PDF/DOCX/EPUB/PPTX/XLSX에서 텍스트 추출.                              |
| `venice_list_models`     | 가격과 함께 실시간 모델 카탈로그 목록.                                         |
| `venice_list_characters` | 공개 Venice 캐릭터 목록.                                              |
| `venice_crypto_rpc`      | Base, Ethereum, Polygon, Arbitrum, Optimism으로 JSON-RPC 호출 프록시. |

### x402 지갑 헬퍼

API 키 대신 [x402](/guides/integrations/x402-venice-api)를 통해 지갑으로 인증할 때만 관련됩니다.

| Tool                       | Description                                   |
| -------------------------- | --------------------------------------------- |
| `venice_x402_balance`      | EVM 또는 Solana 지갑 주소의 선불 x402 크레딧 잔액 확인.       |
| `venice_x402_top_up_info`  | 충전 요건(네트워크, USDC 토큰, 수령자, 최소 금액) 조회.          |
| `venice_x402_transactions` | EVM 또는 Solana 지갑 주소의 최근 x402 충전 및 차감 트랜잭션 목록. |

## 구성

서버는 전적으로 환경 변수로 구성됩니다.

| Env var                      | Default                   | Notes                                              |
| ---------------------------- | ------------------------- | -------------------------------------------------- |
| `VENICE_API_KEY`             | *(없음)*                    | Venice API 키. 가장 간단한 설정.                           |
| `VENICE_DEFAULT_CHAT_MODEL`  | `venice-uncensored`       |                                                    |
| `VENICE_DEFAULT_IMAGE_MODEL` | `flux-2-pro`              |                                                    |
| `VENICE_DEFAULT_TTS_MODEL`   | `tts-kokoro`              |                                                    |
| `VENICE_DEFAULT_ASR_MODEL`   | `openai/whisper-large-v3` |                                                    |
| `VENICE_DISABLE_NSFW`        | `0`                       | `1`로 설정하면 도구 설명에서 NSFW 가능 표시 제거.                   |
| `VENICE_HTTP_TIMEOUT_MS`     | `60000`                   |                                                    |
| `VENICE_SIWX_TOKEN`          | *(없음)*                    | x402 지갑 모드 인증 토큰. [아래 x402](#x402-wallet-mode) 참고. |

`VENICE_API_KEY`와 `VENICE_SIWX_TOKEN`이 모두 설정되어 있으면 API 키가 우선합니다.

## x402 지갑 모드

Venice는 일반 API 키 흐름 외에도 Base 또는 Solana의 선불 USDC 크레딧을 기반으로 한 [Sign-In-With-X 지갑 토큰](/guides/integrations/x402-venice-api)을 통한 인증을 지원합니다. 이메일, 전화번호, KYC 불필요: 지갑이 유일한 신원입니다.

```json theme={"system"}
{
  "mcpServers": {
    "venice": {
      "command": "npx",
      "args": ["-y", "@veniceai/mcp-server@0.2.0"],
      "env": { "VENICE_SIWX_TOKEN": "<base64 Sign-In-With-X payload>" }
    }
  }
}
```

MCP 서버는 모든 Venice API 호출에 `VENICE_SIWX_TOKEN`을 `X-Sign-In-With-X` 헤더로 전달합니다. 서버는 사용자의 private key를 절대 볼 수 없습니다. 지갑 서명과 USDC 충전 승인은 사용자의 지갑 내부에서 발생합니다.

| Flow         | What happens                                                                                                        |
| ------------ | ------------------------------------------------------------------------------------------------------------------- |
| **일회성 설정**   | 지갑에서 Sign-In-With-X 메시지에 서명 → SIWX 토큰(base64 JSON) 생성.                                                              |
| **충전**       | `POST /api/v1/x402/top-up`이 402와 결제 요건을 반환. 반환된 Base 또는 Solana 옵션 중 하나에 대한 USDC 결제를 서명하고 재제출하면, Venice가 잔액에 크레딧합니다. |
| **모든 추론 호출** | MCP 서버가 `X-Sign-In-With-X: <SIWX>`를 보내고, Venice가 선불 잔액을 차감.                                                         |

최소 충전액은 **$5 USD**. 추론 호출을 위한 최소 잔액은 **$0.10**. 한 번 충전하면 정산이 빠른 크레딧 계정의 오프체인에서 일어나므로 호출은 100ms 미만입니다.

<Tip>
  DIEM이 스테이킹된 Venice 계정에 연결된 지갑은 USDC 크레딧 대신 스테이킹 잔액에서 소비하므로 충전이 필요 없습니다.
</Tip>

## 셀프 호스팅(Streamable HTTP)

팀이나 워크스페이스 배포의 경우 stdio 대신 HTTP로 MCP 서버를 실행하세요:

```bash theme={"system"}
docker run -p 3333:3333 \
  -e VENICE_API_KEY=<your-venice-api-key> \
  -e VENICE_MCP_AUTH_TOKEN=<choose-a-long-random-token> \
  ghcr.io/veniceai/venice-mcp-server:latest
```

이제 서버는 `http://localhost:3333/mcp`에서 사용 가능합니다. HTTP 클라이언트는 `Authorization: Bearer <VENICE_MCP_AUTH_TOKEN>`을 전송해야 합니다.

<Warning>
  `/mcp`는 자격 증명 기반 도구 실행 endpoint입니다: 호출자는 구성된 Venice API 키나 x402 잔액을 소비할 수 있습니다. HTTP 모드가 loopback 외부에 바인딩될 때 `VENICE_MCP_AUTH_TOKEN`이 설정되지 않으면 시작이 실패합니다. 프로덕션에서는 `latest`에 의존하지 말고 npm 패키지 버전을 명시적으로 고정하세요.
</Warning>

## 리소스

<CardGroup cols={2}>
  <Card title="GitHub" icon="github" href="https://github.com/veniceai/venice-mcp-server">
    소스 코드, 이슈, 릴리스
  </Card>

  <Card title="npm" icon="npm" href="https://www.npmjs.com/package/@veniceai/mcp-server">
    `@veniceai/mcp-server`
  </Card>

  <Card title="Venice Skills" icon="book" href="/guides/integrations/venice-skills">
    이 도구들의 사용법을 에이전트에게 가르치는 동반 스킬
  </Card>

  <Card title="MCP 스펙" icon="arrow-up-right-from-square" href="https://modelcontextprotocol.io/">
    Model Context Protocol에 대해 더 알아보기
  </Card>
</CardGroup>