Vox MCP

Vox MCP

MCP クライアント向けのマルチモデル AI ゲートウェイです。

概要

Claude Code、Claude Desktop、Cursor などの MCP クライアントでは、ホストのモデルしか使用できません。Vox を使うと、単一の chat ツールを通じて、Gemini、GPT、Grok、DeepSeek、Kimi、またはローカルの Ollama など、ほかのすべてのモデルを利用できます。

設計は意図的に最小限にしています。プロンプトは変更せずにプロバイダーへ送信し、レスポンスも変更せずに返します。システムプロンプトの挿入はありません。レスポンスの整形もありません。動作指示もありません。Vox が追加する価値はルーティングと会話メモリだけで、それ以外はすべてそのまま受け渡します。

機能

プロンプトを送信し、必要に応じてファイルや画像を添付し、モデルを選択するかエージェントに選択させると、モデルの生のレスポンスが返されます。会話スレッドは 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 の場合、呼び出し元のエージェントが利用可能なモデルを選択します。Vox が選択する必要がある場合は、既存のプロバイダー優先順位が適用されます。明示的に指定したモデルまたは構成済みのデフォルトが優先されます。GPT-6 Sol/Luna、Grok 4.7、Claude Fable 5.1、Sonnet 5、Haiku 4.5 も引き続き選択できます。アクセス権のあるアカウントでは、Claude 3 Opus の固定スナップショットも引き続き利用できます。

プロバイダーの優先設定、正確な API ID、推論の動作については、モデルの選択と検証に使用した情報源をご覧ください。

クイックスタート

公開パッケージ

uv をインストールしたら、MCP クライアントの構成に Vox を追加します。たとえば、OpenAI を使用する場合：

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

上の表から、使用するプロバイダーの環境変数を設定してください。必要なプロバイダーは 1 つだけです。サーバーに接続したら、エージェントに 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 キーは 1 つだけです。プロバイダーは後から .env 経由で追加できます
• vox-mcp ディレクトリ内の .env ファイルは自動的に読み込まれるため、API キーはクライアント設定ではなく、こちらに記述することもできます
• クライアントから渡される環境変数と .env の値が競合する場合は、.env で VOX_FORCE_ENV_OVERRIDE=true を使用してください

設定

MCP クライアントの Vox env オブジェクトで、次の値を設定します。ソースコードをチェックアウトしている場合は、代わりに .env.example を .env にコピーできます：

• API キー — 少なくとも 1 つのプロバイダーキーが必要です
• DEFAULT_MODEL — 保存済みのモデル設定を上書きします。auto を指定すると、エージェントに選択を任せます
• 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 以降で利用できます。MCP クライアントの設定を編集せずに、自分またはエージェントがデフォルトを保存できます。たとえば、GPT-6 Astra を選択するには：

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

gpt-6-astra を、kimi-k3、grok-4.6、claude-opus-5-5、claude-fable-5-1、deepseek-flash、gemini-3.8-flash など、利用可能な任意のモデル ID に置き換えてください。保存済みの設定を削除するには、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 です。そのため、保存済みのデフォルトが変更されるのは新しい会話であり、既存のスレッドは切り替わりません。1 つの MCP クライアントで保存済みの設定を上書きするには、Vox サーバーの env オブジェクトに "DEFAULT_MODEL": "your-model-id" を追加してください。ソースコードをチェックアウトしている場合は、既存の .env 設定も引き続き環境変数として優先されます。自動的に読み込まれる .env は Vox のインストール先に属し、現在のディレクトリには属しません。uvx でインストールした場合は、設定コマンドまたは MCP クライアントの環境を使用してください。

auto の場合、呼び出しごとにモデルを選択するようエージェントに指示されます。呼び出し元が model: "auto" を渡した場合、Vox は組み込みのプロバイダー優先順位と設定を使用します。これは、すべてのプロバイダーをリアルタイムで比較するものではありません。明示的なモデル選択はいつでも利用できます。ターミナルにアクセスできるエージェントなら、次の操作を実行できます：

Vox の listmodels を使用して、GPT-6 Astra が利用可能か確認してください。config コマンドで Vox のデフォルトとして保存し、DEFAULT_MODEL がそれを上書きするか確認して、Vox に再接続する方法を教えてください。

Vox の 3 つの MCP ツールしか利用できないエージェントは、呼び出しごとにモデルを選択できますが、設定を保持できません。設定の保存には、ターミナルまたはファイルへのアクセスが必要です。

Cloudflare and 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 account REST API を https://api.cloudflare.com/client/v4/accounts/<account>/ai/v1 で使用し、ベアラートークンで認証して、cf-aig-gateway-id を設定します（設定がない場合は default）。トークンには Workers AI Read 権限が必要です。AI Gateway 専用のトークンでは不十分です。サードパーティモデルは 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 は https://ai-gateway.vercel.sh/v1 にある Vercel's OpenAI-compatible API を使用します。AI_GATEWAY_API_KEY も使用できます。両方が設定されている場合は、VERCEL_AI_GATEWAY_API_KEY が優先されます。

カタログと制限

CLOUDFLARE_MODELS と VERCEL_MODELS は、listmodels とエージェント検出に使う、任意のカンマ区切りのアップストリーム ID です。これらによってアクセスが制限されることはありません。デフォルトの DEFAULT_MODEL=auto を使用している場合も含め、カタログがなくても明示的なゲートウェイモデル ID を使用できます。ゲートウェイモデルは呼び出し元が指定する必要があります。アクセスを制限するには、CLOUDFLARE_ALLOWED_MODELS または VERCEL_ALLOWED_MODELS を使用してください。カタログと許可リストでは、アップストリーム ID と完全なプレフィックス付きの Vox ルートの両方が受け入れられます。ゲートウェイが公開している正確なモデル ID を使用してください。ネイティブプロバイダーとゲートウェイの ID は異なる場合があります。

ゲートウェイリクエストは現在、テキストのみをサポートしています。Vox はモデル名からビジョンや思考の制御を推測しません。明示的なゲートウェイの thinking_mode リクエストは推論の前に拒否されます。32,768 トークンのコンテキストと 4,096 トークンの出力予算は、保守的なローカル推定値であり、アップストリームが公表している上限ではありません。これらの数値は生成パラメーターとして送信されません。温度や推論設定を省略した場合は、アップストリームのデフォルトが使用されます。起動時にカタログやモデルの利用可能性を確認するリクエストは行われません。アダプターはモック 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 を基にしています。