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

> The official Venice Model Context Protocol server exposes 31 Venice tools for chat, image, video, audio, music, and characters in any MCP host.

The [Venice MCP Server](https://github.com/veniceai/venice-mcp-server) is the official [Model Context Protocol](https://modelcontextprotocol.io/) server for Venice. It exposes the full Venice API (chat, image, video, audio, music, embeddings, web augment, and characters) as **31 tools** that any MCP-compatible agent can call.

<Card title="GitHub: veniceai/venice-mcp-server" icon="github" href="https://github.com/veniceai/venice-mcp-server">
  Published as [`@veniceai/mcp-server`](https://www.npmjs.com/package/@veniceai/mcp-server) on npm. MIT licensed.
</Card>

<CardGroup cols={3}>
  <Card title="31 Tools" icon="toolbox">
    Every Venice modality in one config block
  </Card>

  <Card title="Any MCP Host" icon="plug">
    Claude Desktop, Cursor, ChatGPT, LM Studio, Continue, and more
  </Card>

  <Card title="Wallet Auth (Optional)" icon="wallet">
    Bring an API key, or pay per call with a SIWE-signed wallet via x402
  </Card>
</CardGroup>

## Quick start

<Steps>
  <Step title="Get a Venice API key">
    Generate one from [venice.ai/settings/api](https://venice.ai/settings/api). See the [API key guide](/guides/getting-started/generating-api-key) for step-by-step instructions.
  </Step>

  <Step title="Add Venice to your MCP host config">
    Drop this into your MCP host's config file:

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

    Common config paths:

    | 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.json` (from the app's MCP settings)                          |
  </Step>

  <Step title="Restart your MCP host">
    Your agent now has chat, image, video, music, TTS, ASR, and 25 more Venice tools available.
  </Step>
</Steps>

<Note>
  Most MCP hosts only pass environment variables that are **explicitly listed** in the `env` block. System-level env vars are not inherited. If you see 402 errors with an API key set, double-check that `VENICE_API_KEY` is inside `env` in your config.
</Note>

## What you get

**31 tools** spanning every Venice modality, **3 resources** (`venice://models`, `venice://styles`, `venice://voices`), and **3 prompt templates**.

### Chat & embeddings

| Tool                         | Description                                                              |
| ---------------------------- | ------------------------------------------------------------------------ |
| `venice_chat`                | OpenAI-compatible chat completion against Venice's full LLM catalog.     |
| `venice_responses`           | OpenAI-compatible Responses API with single- or multi-turn tool support. |
| `venice_embeddings`          | Compute embeddings for text input.                                       |
| `venice_chat_with_character` | Chat with a Venice character by slug.                                    |

### Image

| Tool                      | Description                                                                                            |
| ------------------------- | ------------------------------------------------------------------------------------------------------ |
| `venice_image_generate`   | Generate an image (Flux 2, Lustify SDXL, Anime/WAI, Qwen Image, GPT Image, Nano Banana Pro, and more). |
| `venice_image_edit`       | Edit an image with a prompt.                                                                           |
| `venice_image_multi_edit` | Edit multiple images together with one prompt.                                                         |
| `venice_image_upscale`    | Upscale an image up to 4×.                                                                             |
| `venice_image_remove_bg`  | Remove an image background.                                                                            |
| `venice_image_styles`     | List image style presets.                                                                              |

### Video

| Tool                          | Description                                                                                      |
| ----------------------------- | ------------------------------------------------------------------------------------------------ |
| `venice_video_generate`       | Queue a video generation (Sora 2, Veo 3.1, Kling, Wan, LTX 2, Seedance, Runway Gen-4, and more). |
| `venice_video_status`         | Check status of a queued video job.                                                              |
| `venice_video_complete`       | Mark a completed video as downloaded; deletes server-side media.                                 |
| `venice_video_transcriptions` | Transcribe a YouTube video URL.                                                                  |
| `venice_video_quote`          | Get a price quote before queuing.                                                                |

### Audio (TTS / ASR)

| Tool                 | Description                                          |
| -------------------- | ---------------------------------------------------- |
| `venice_tts`         | Text-to-speech with cloned voices and emotion tags.  |
| `venice_asr`         | Transcribe audio from a URL.                         |
| `venice_voice_clone` | List built-in voices or clone a voice from a sample. |
| `venice_audio_quote` | Get a price quote for music generation.              |

### Music

| Tool                    | Description                                                                                                                                             |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `venice_music_generate` | Queue music generation (`ace-step-15`, `elevenlabs-music`, `minimax-music-v2/v25/v26`, `stable-audio-25`, `mmaudio-v2`, `elevenlabs-sound-effects-v2`). |
| `venice_music_status`   | Check status of a queued music job.                                                                                                                     |
| `venice_music_complete` | Mark a completed music job as downloaded.                                                                                                               |

### Web augment, catalog, and crypto

| Tool                     | Description                                                             |
| ------------------------ | ----------------------------------------------------------------------- |
| `venice_web_search`      | Search the web (Firecrawl-backed).                                      |
| `venice_web_scrape`      | Scrape one URL into markdown.                                           |
| `venice_text_parser`     | Extract text from PDF/DOCX/EPUB/PPTX/XLSX.                              |
| `venice_list_models`     | List the live model catalog with prices.                                |
| `venice_list_characters` | List public Venice characters.                                          |
| `venice_crypto_rpc`      | Proxy JSON-RPC calls to Base, Ethereum, Polygon, Arbitrum, or Optimism. |

### x402 wallet helpers

Only relevant if you authenticate with a wallet via [x402](/guides/integrations/x402-venice-api) instead of an API key.

| Tool                       | Description                                                                         |
| -------------------------- | ----------------------------------------------------------------------------------- |
| `venice_x402_balance`      | Check prepaid x402 credit balance for an EVM or Solana wallet address.              |
| `venice_x402_top_up_info`  | Fetch top-up requirements (network, USDC token, receiver, min amount).              |
| `venice_x402_transactions` | List recent x402 top-up and debit transactions for an EVM or Solana wallet address. |

## Configuration

The server is configured entirely through environment variables.

| Env var                      | Default                   | Notes                                                              |
| ---------------------------- | ------------------------- | ------------------------------------------------------------------ |
| `VENICE_API_KEY`             | *(none)*                  | Your Venice API key. The simplest setup.                           |
| `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`                       | Set to `1` to remove NSFW capability notes from tool descriptions. |
| `VENICE_HTTP_TIMEOUT_MS`     | `60000`                   |                                                                    |
| `VENICE_SIWX_TOKEN`          | *(none)*                  | x402 wallet-mode auth token. See [x402 below](#x402-wallet-mode).  |

If both `VENICE_API_KEY` and `VENICE_SIWX_TOKEN` are set, the API key wins.

## x402 wallet mode

Venice supports authenticating with a [Sign-In-With-X wallet token](/guides/integrations/x402-venice-api) backed by prepaid USDC credit on Base or Solana, in addition to the normal API key flow. No email, phone, or KYC required: your wallet is the only identity.

```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>" }
    }
  }
}
```

The MCP server forwards `VENICE_SIWX_TOKEN` as the `X-Sign-In-With-X` header on every Venice API call. The server never sees your private key. Wallet signing and USDC top-up authorizations happen in your own wallet.

| Flow                     | What happens                                                                                                                                                                  |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **One-time setup**       | Sign a Sign-In-With-X message in your wallet → produces a SIWX token (base64 JSON).                                                                                           |
| **Top up**               | `POST /api/v1/x402/top-up` returns 402 + payment requirements. Sign a USDC payment for one of the returned Base or Solana options, resubmit, and Venice credits your balance. |
| **Every inference call** | MCP server sends `X-Sign-In-With-X: <SIWX>`; Venice debits your prepaid balance.                                                                                              |

Minimum top-up is **\$5 USD**. Minimum balance to call inference is **\$0.10**. Once topped up, calls are sub-100ms because settlement happens off-chain on a fast credit account.

<Tip>
  Wallets linked to a Venice account with DIEM staked consume from the staking balance instead of USDC credits, so no top-up is needed.
</Tip>

## Self-hosting (Streamable HTTP)

For team or workspace deployments, run the MCP server over HTTP instead of stdio:

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

The server is now available at `http://localhost:3333/mcp`. HTTP clients must send `Authorization: Bearer <VENICE_MCP_AUTH_TOKEN>`.

<Warning>
  `/mcp` is a credential-backed tool execution endpoint: callers can spend the configured Venice API key or x402 balance. When HTTP mode binds outside loopback, startup fails unless `VENICE_MCP_AUTH_TOKEN` is set. For production, pin the npm package version explicitly instead of relying on `latest`.
</Warning>

## Resources

<CardGroup cols={2}>
  <Card title="GitHub" icon="github" href="https://github.com/veniceai/venice-mcp-server">
    Source code, issues, and releases
  </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">
    Companion skills that teach agents how to use these tools
  </Card>

  <Card title="MCP Spec" icon="arrow-up-right-from-square" href="https://modelcontextprotocol.io/">
    Learn more about the Model Context Protocol
  </Card>
</CardGroup>