Vox MCP

Vox MCP

面向 MCP 客户端的多模型 AI 网关。

为什么要用

Claude Code、Claude Desktop 和 Cursor 等 MCP 客户端只能使用其宿主模型。Vox 通过一个 chat 工具，让它们能够访问其他所有模型——Gemini、GPT、Grok、DeepSeek、Kimi，或本地 Ollama。

设计刻意保持精简：提示词原样发送给提供商，响应原样返回。不注入系统提示词。不格式化响应。不添加行为指令。Vox 唯一提供的价值是路由和对话记忆——其他一切都是纯粹透传。

功能

发送提示词，可选择附加文件或图片，指定模型（或让 Agent 选择），即可获得模型的原始响应。对话线程会通过 continuation_id 保存在内存中，支持跨提供商进行多轮对话——从 Gemini 开始一个线程，再用 GPT 继续。线程还会以 JSONL 格式影子持久化到磁盘，以确保耐久性，并可导出为 Markdown。

3 个工具：

工具	描述
chat	向任意已配置的 AI 模型发送提示词，可选附带文件/图片上下文
listmodels	显示可用模型、别名和能力
dump_threads	将对话线程导出为 JSON 或 Markdown

10 个提供商：

提供商	环境变量	内置首选项或路由
Google Gemini	GEMINI_API_KEY	gemini-3.8-flash；扩展推理使用 gemini-3.1-pro-preview
OpenAI	OPENAI_API_KEY	gpt-6-astra
Anthropic	ANTHROPIC_API_KEY	claude-opus-5-5，其次为 claude-fable-5-1
xAI	XAI_API_KEY	grok-4.6
DeepSeek	DEEPSEEK_API_KEY	deepseek-flash（V4.1 Flash）
Moonshot (Kimi)	MOONSHOT_API_KEY	kimi-k3
OpenRouter	OPENROUTER_API_KEY	显式指定的 OpenRouter 模型 ID 或精选别名
Cloudflare AI Gateway	CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID	cloudflare/<provider>/<model>
Vercel AI Gateway	VERCEL_AI_GATEWAY_API_KEY 或 AI_GATEWAY_API_KEY	vercel/<provider>/<model>
Custom	CUSTOM_API_URL	Ollama、vLLM、LM Studio 等

这些是各提供商内部的首选项。使用 auto 时，由调用方 Agent 选择可用模型；如果必须由 Vox 选择，则沿用现有的提供商优先级。显式指定的模型或已配置的默认值具有更高优先级。GPT-6 Sol/Luna、Grok 4.7、Claude Fable 5.1、Sonnet 5 和 Haiku 4.5 仍可供选择。Claude 3 Opus 的固定快照会为拥有访问权限的账户保留。

有关提供商首选项、准确的 API ID 和推理行为，请参阅模型选择和验证来源。

快速开始

已发布的软件包

安装 uv 后，将 Vox 添加到 MCP 客户端的配置中。以下示例使用 OpenAI：

{
  "mcpServers": {
    "vox-mcp": {
      "command": "uvx",
      "args": ["vox-mcp"],
      "env": {
        "OPENAI_API_KEY": "your-key-here"
      }
    }
  }
}

使用上表中首选提供商对应的环境变量。只需配置一个提供商。连接服务后，让 Agent 调用 listmodels，即可查看当前配置下可用的模型。

如需使用指定版本，请使用 "args": ["[email protected]"]。要刷新缓存的安装，请运行 uvx --refresh vox-mcp config show，然后重新连接 MCP 服务。客户端配置中固定的版本也必须在配置中更新。

源码检出

git clone https://github.com/linxule/vox-mcp.git
cd vox-mcp
cp .env.example .env
# Edit .env — add at least one API key
uv sync
uv run python server.py

MCP 客户端配置

Vox 以 stdio MCP 服务的形式运行。每个客户端都需要知道如何启动它。以下示例使用源码检出；上文的已发布软件包配置无需克隆仓库。请将 /path/to/vox-mcp 替换为所克隆仓库的绝对路径。

Claude Code（CLI）

claude mcp add vox-mcp \
  -e GEMINI_API_KEY=your-key-here \
  -- uv run --directory /path/to/vox-mcp python server.py

或者将以下内容添加到项目根目录中的 .mcp.json：

{
  "mcpServers": {
    "vox-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/vox-mcp", "python", "server.py"],
      "env": {
        "GEMINI_API_KEY": "your-key-here"
      }
    }
  }
}

Claude Desktop

添加到 claude_desktop_config.json：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json Windows： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "vox-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/vox-mcp", "python", "server.py"],
      "env": {
        "GEMINI_API_KEY": "your-key-here"
      }
    }
  }
}

Cursor

添加到 .cursor/mcp.json（项目级）或 ~/.cursor/mcp.json（全局）：

{
  "mcpServers": {
    "vox-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/vox-mcp", "python", "server.py"],
      "env": {
        "GEMINI_API_KEY": "your-key-here"
      }
    }
  }
}

Windsurf

添加到 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "vox-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/vox-mcp", "python", "server.py"],
      "env": {
        "GEMINI_API_KEY": "your-key-here"
      }
    }
  }
}

任意 MCP 客户端

标准 stdio 配置：

{
  "mcpServers": {
    "vox-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/vox-mcp", "python", "server.py"],
      "env": {
        "GEMINI_API_KEY": "your-key-here"
      }
    }
  }
}

提示：

• 路径必须是绝对路径
• 只需一个 API 密钥即可开始使用；之后可以通过 .env 添加更多提供商
• vox-mcp 目录中的 .env 文件会自动加载，因此可以将 API 密钥放在那里，而不是放在客户端配置中
• 如果客户端传入的环境变量与 .env 中的值冲突，请在 .env 中使用 VOX_FORCE_ENV_OVERRIDE=true

配置

在 MCP 客户端的 Vox env 对象中设置以下值。对于源码检出版本， 也可以将 .env.example 复制为 .env：

• API 密钥 — 至少需要一个提供商的密钥
• DEFAULT_MODEL — 覆盖已保存的模型偏好；auto 会让 Agent 选择
• VOX_CONFIG_PATH — 可选的设置文件路径（默认值：~/.vox/config.json）
• 模型限制 — GOOGLE_ALLOWED_MODELS、OPENAI_ALLOWED_MODELS 等
• CONVERSATION_TIMEOUT_HOURS — 对话线程 TTL（默认值：24h）
• MAX_CONVERSATION_TURNS — 对话线程长度限制（默认值：100）

完整参考请参阅 .env.example。

设置默认模型

自 0.8.0 起提供。你或你的 Agent 可以保存默认模型，而无需编辑 MCP 客户端配置。例如，选择 GPT-6 Astra：

uvx vox-mcp config set-default gpt-6-astra
uvx vox-mcp config show

将 gpt-6-astra 替换为任意可用的模型 ID，例如 kimi-k3、grok-4.6、 claude-opus-5-5、claude-fable-5-1、deepseek-flash 或 gemini-3.8-flash。 要移除已保存的偏好，请运行 uvx vox-mcp config reset-default。

对于源码检出版本，请使用 uv run vox-mcp config ...。偏好设置保存在 ~/.vox/config.json 中；设置 VOX_CONFIG_PATH 可使用其他文件。此文件保存的是 模型偏好，而非 API 密钥。命令不会发起模型请求，也不需要提供商凭据。在已连接的 MCP 客户端中使用 listmodels，即可选择可用的 ID 或别名。也可以保存 vercel/google/gemini-3.1-pro-preview 这类显式网关路由。ID 会原样保留； 保存默认模型不会验证你的账户是否有权访问该模型。

更改设置后，请重启或重新连接 Vox。config show 会显示已保存的默认模型、 生效的默认模型及其来源，这些信息对应命令的启动环境。正在运行的 MCP 客户端 环境可能不同；listmodels 会报告其服务实际加载的默认模型。

选择顺序为：显式指定的 chat.model、继续对话线程时使用的上一个模型、 服务环境中的 DEFAULT_MODEL、已保存的默认模型，然后是 auto。 因此，已保存的默认模型会影响新对话，但不会切换现有线程。要为某个 MCP 客户端覆盖已保存的偏好，请在 Vox 服务的 env 对象中添加 "DEFAULT_MODEL": "your-model-id"。现有源码检出版本的 .env 设置仍保有 其环境优先级。自动加载的 .env 属于 Vox 安装目录，而非当前目录；对于 uvx 安装，请使用设置命令或 MCP 客户端环境。

使用 auto 时，系统会要求 Agent 为每次调用选择模型。如果调用方传入 model: "auto"，Vox 会使用内置的提供商优先级和偏好；这并非对所有提供商进行 实时比较。显式选择模型始终可用。有终端访问权限的 Agent 可以为你执行以下操作：

使用 Vox listmodels 检查 GPT-6 Astra 是否可用。使用 config 命令将其保存为我的 Vox 默认模型，检查 DEFAULT_MODEL 是否会覆盖它，并告诉我如何重新连接 Vox。

只有 Vox 的三个 MCP 工具的 Agent 可以为每次调用选择模型，但 无法持久保存偏好；保存设置需要终端或文件访问权限。

Cloudflare 和 Vercel AI Gateway

在 chat.model 中使用显式的网关前缀。Vox 只会在发送请求前移除第一个前缀，并将其保留在对话记忆中。缺少网关配置或模型不被允许时，请求会失败，不会回退到 OpenRouter 或原生提供商。裸模型名称仍按现有路由行为处理。

Cloudflare

CLOUDFLARE_API_TOKEN=your-cloudflare-token
CLOUDFLARE_ACCOUNT_ID=your-account-id
CLOUDFLARE_GATEWAY_ID=default
CLOUDFLARE_MODELS=openai/gpt-5.5

{"prompt": "Explain quorum consensus.", "model": "cloudflare/openai/gpt-5.5"}

Vox 使用 Cloudflare 账户 REST API，接口地址为 https://api.cloudflare.com/client/v4/accounts/<account>/ai/v1，通过 bearer token 进行身份验证，并设置 cf-aig-gateway-id（除非另行配置，否则为 default）。该 token 需要 Workers AI Read 权限；仅限 AI Gateway 的 token 不够用。第三方模型使用 Cloudflare Unified Billing。Workers AI 模型 ID 保留其 @cf/ 前缀，例如 cloudflare/@cf/moonshotai/kimi-k2.6。此适配器不支持旧版 /compat、提供商密钥转发和 dynamic/ 路由。

Vercel

VERCEL_AI_GATEWAY_API_KEY=your-vercel-gateway-key
VERCEL_MODELS=anthropic/claude-sonnet-4.6

{"prompt": "Explain quorum consensus.", "model": "vercel/anthropic/claude-sonnet-4.6"}

Vox 使用 Vercel 的 OpenAI 兼容 API，接口地址为 https://ai-gateway.vercel.sh/v1。也接受 AI_GATEWAY_API_KEY；如果两者都已设置，则优先使用 VERCEL_AI_GATEWAY_API_KEY。

目录和限制

CLOUDFLARE_MODELS 和 VERCEL_MODELS 是可选的逗号分隔上游 ID，供 listmodels 和 Agent 发现使用。它们不会限制访问。显式的网关模型 ID 无需目录即可使用，包括默认的 DEFAULT_MODEL=auto；调用方必须提供网关模型。使用 CLOUDFLARE_ALLOWED_MODELS 或 VERCEL_ALLOWED_MODELS 可限制访问。目录和允许列表均接受上游 ID 和带完整前缀的 Vox 路由。请使用网关发布的确切模型 ID；原生提供商 ID 和网关 ID 可能不同。

网关请求目前仅支持文本。Vox 不会根据模型名称推断视觉或思考控制；显式的网关 thinking_mode 请求会在推理前被拒绝。其 32,768 个 token 的上下文预算和 4,096 个 token 的输出预算是保守的本地估算，并非上游公布的限制；这些数字不会作为生成参数发送。未指定温度和推理设置时，将使用上游默认值。启动时不会请求目录或模型可用性信息。适配器通过模拟 HTTP 测试进行验证；实时推理需要配置账户，且未纳入发布检查。

开发

依赖项在 pyproject.toml 和 uv.lock 中维护；Dependabot 通过其 uv 集成更新锁定文件，同时遵守受支持的版本范围。更改这些范围需要进行有意的兼容性审查。CI 会检查锁定文件，在 Python 3.10 和 3.13 上运行离线测试套件，并使用 pip-audit 审计锁定的包。 支持的 SDK 版本系列为 MCP 1.x、OpenAI 2.x 和 Anthropic 0.x。 MCP SDK 2 需要单独迁移服务 API；提供商的主要版本升级与依赖维护分开进行。

uv sync
uv run python -c "import server"   # smoke test
uv run pytest                       # run tests

代码风格、项目结构以及如何添加提供商，请参阅 CONTRIBUTING.md。

许可证

Apache 2.0 — 请参阅 LICENSE 和 NOTICE。

基于 Beehive Innovations 的 pal-mcp-server 派生而来。