> ## Documentation Index
> Fetch the complete documentation index at: https://veniceai-docs-responses-api.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Venice MCP Server

> The official Venice MCP server exposes 31 tools for chat, image, video, audio, and embeddings to Claude Desktop, Cursor, and 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="brand-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="tool">
    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?utm_source=venice-api-documentation). 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={null}
    {
      "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_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={null}
{
  "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={null}
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="brand-github" href="https://github.com/veniceai/venice-mcp-server">
    Source code, issues, and releases
  </Card>

  <Card title="npm" icon="brand-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="external-link" href="https://modelcontextprotocol.io/">
    Learn more about the Model Context Protocol
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.