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

> 官方 Venice Model Context Protocol 服务器在任何 MCP 宿主中暴露 31 个 Venice 工具，用于聊天、图像、视频、音频、音乐和角色。

[Venice MCP Server](https://github.com/veniceai/venice-mcp-server) 是 Venice 的官方 [Model Context Protocol](https://modelcontextprotocol.io/) 服务器。它将完整的 Venice API（聊天、图像、视频、音频、音乐、embeddings、web augment 和 character）作为 **31 个工具**暴露给任何兼容 MCP 的 agent。

<Card title="GitHub: veniceai/venice-mcp-server" icon="github" href="https://github.com/veniceai/venice-mcp-server">
  以 [`@veniceai/mcp-server`](https://www.npmjs.com/package/@veniceai/mcp-server) 发布到 npm。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="将 Venice 添加到 MCP 宿主配置">
    将以下内容放入您的 MCP 宿主配置文件：

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

    常见配置路径：

    | 宿主                       | 路径                                                                |
    | ------------------------ | ----------------------------------------------------------------- |
    | 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`（从应用的 MCP 设置中获取）                                        |
  </Step>

  <Step title="重启您的 MCP 宿主">
    您的 agent 现在已具备聊天、图像、视频、音乐、TTS、ASR 以及 25 个其他 Venice 工具。
  </Step>
</Steps>

<Note>
  大多数 MCP 宿主只会传递在 `env` 块中**显式列出**的环境变量。系统级环境变量不会被继承。如果您在设置了 API 密钥后仍看到 402 错误，请仔细检查 `VENICE_API_KEY` 是否在配置的 `env` 中。
</Note>

## 您将获得

**31 个工具**，覆盖每种 Venice 模态；**3 个资源**（`venice://models`、`venice://styles`、`venice://voices`）；**3 个 prompt 模板**。

### 聊天与 embeddings

| 工具                           | 说明                                  |
| ---------------------------- | ----------------------------------- |
| `venice_chat`                | 针对 Venice 完整 LLM 目录的 OpenAI 兼容聊天补全。 |
| `venice_responses`           | 支持单轮或多轮工具的 OpenAI 兼容 Responses API。 |
| `venice_embeddings`          | 计算文本输入的 embeddings。                 |
| `venice_chat_with_character` | 按 slug 与 Venice character 聊天。       |

### 图像

| 工具                        | 说明                                                                          |
| ------------------------- | --------------------------------------------------------------------------- |
| `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`     | 列出图像风格预设。                                                                   |

### 视频

| 工具                            | 说明                                                              |
| ----------------------------- | --------------------------------------------------------------- |
| `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）

| 工具                   | 说明                       |
| -------------------- | ------------------------ |
| `venice_tts`         | 文本转语音，支持克隆 voice 和情感标签。  |
| `venice_asr`         | 从 URL 转录音频。              |
| `venice_voice_clone` | 列出内置 voice 或从样本克隆 voice。 |
| `venice_audio_quote` | 获取音乐生成的价格报价。             |

### 音乐

| 工具                      | 说明                                                                                                                                |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `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` | 将已完成音乐作业标记为已下载。                                                                                                                   |

### Web augment、目录和 crypto

| 工具                       | 说明                                                           |
| ------------------------ | ------------------------------------------------------------ |
| `venice_web_search`      | 搜索 web（由 Firecrawl 支持）。                                      |
| `venice_web_scrape`      | 将一个 URL 抓取为 markdown。                                        |
| `venice_text_parser`     | 从 PDF/DOCX/EPUB/PPTX/XLSX 提取文本。                              |
| `venice_list_models`     | 列出实时的模型目录与价格。                                                |
| `venice_list_characters` | 列出公开的 Venice characters。                                     |
| `venice_crypto_rpc`      | 代理对 Base、Ethereum、Polygon、Arbitrum 或 Optimism 的 JSON-RPC 调用。 |

### x402 钱包辅助

仅当您通过 [x402](/guides/integrations/x402-venice-api) 使用钱包而非 API 密钥进行身份验证时相关。

| 工具                         | 说明                                    |
| -------------------------- | ------------------------------------- |
| `venice_x402_balance`      | 检查 EVM 或 Solana 钱包地址的预付 x402 额度余额。    |
| `venice_x402_top_up_info`  | 获取充值要求（网络、USDC 代币、接收方、最低金额）。          |
| `venice_x402_transactions` | 列出 EVM 或 Solana 钱包地址近期的 x402 充值和扣款交易。 |

## 配置

服务器完全通过环境变量配置。

| 环境变量                         | 默认值                       | 备注                                                    |
| ---------------------------- | ------------------------- | ----------------------------------------------------- |
| `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 钱包模式身份验证 token。请参阅[下方的 x402](#x402-wallet-mode)。 |

如果同时设置了 `VENICE_API_KEY` 和 `VENICE_SIWX_TOKEN`，API 密钥优先。

## x402 钱包模式

除了正常的 API 密钥流程外，Venice 还支持使用由 Base 或 Solana 上预付 USDC 额度支持的 [Sign-In-With-X 钱包 token](/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` 请求头转发。服务器永远看不到您的私钥。钱包签名和 USDC 充值授权在您自己的钱包中进行。

| 流程         | 发生什么                                                                                               |
| ---------- | -------------------------------------------------------------------------------------------------- |
| **一次性设置**  | 在钱包中签署一个 Sign-In-With-X 消息 → 产生一个 SIWX token（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）

对于团队或工作区部署，通过 HTTP 而非 stdio 运行 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` 是一个由凭证支持的工具执行端点：调用方可花费配置的 Venice API 密钥或 x402 余额。当 HTTP 模式绑定在 loopback 之外时，除非设置了 `VENICE_MCP_AUTH_TOKEN`，否则启动会失败。对于生产环境，请显式锁定 npm 包版本，而不是依赖 `latest`。
</Warning>

## 资源

<CardGroup cols={2}>
  <Card title="GitHub" icon="github" href="https://github.com/veniceai/venice-mcp-server">
    源代码、issues 和发布
  </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">
    教 agent 如何使用这些工具的配套 skills
  </Card>

  <Card title="MCP 规范" icon="arrow-up-right-from-square" href="https://modelcontextprotocol.io/">
    了解更多关于 Model Context Protocol
  </Card>
</CardGroup>