{
  "markdown": "# Vox MCP\n\nMulti-model AI gateway for [MCP](https://modelcontextprotocol.io) clients.\n\n## Why\n\nMCP clients like Claude Code, Claude Desktop, and Cursor are locked to their host model. Vox gives them access to every other model — Gemini, GPT, Grok, DeepSeek, Kimi, or your local Ollama — through a single `chat` tool.\n\nThe design is deliberately minimal: prompts go to providers unmodified, responses come back unmodified. No system prompt injection. No response formatting. No behavioral directives. The only value Vox adds is routing and conversation memory — everything else is pure passthrough.\n\n## What it does\n\nSend a prompt, optionally attach files or images, pick a model (or let the agent pick), and get back the model's raw response. Conversation threads persist in memory via `continuation_id` for multi-turn exchanges across any provider — start a thread with Gemini, continue it with GPT. Threads are shadow-persisted to disk as JSONL for durability and can be exported as Markdown.\n\n**3 tools:**\n\n| Tool | Description |\n|------|-------------|\n| `chat` | Send prompts to any configured AI model with optional file/image context |\n| `listmodels` | Show available models, aliases, and capabilities |\n| `dump_threads` | Export conversation threads as JSON or Markdown |\n\n**8 providers:**\n\n| Provider | Env Variable | Example Models |\n|----------|-------------|----------------|\n| Google Gemini | `GEMINI_API_KEY` | gemini-2.5-pro |\n| OpenAI | `OPENAI_API_KEY` | gpt-5.1, gpt-5, o3, o4-mini |\n| Anthropic | `ANTHROPIC_API_KEY` | claude-opus-4-8, claude-sonnet-5, claude-haiku-4-5 |\n| xAI | `XAI_API_KEY` | grok-4.5, grok-4.3 |\n| DeepSeek | `DEEPSEEK_API_KEY` | deepseek-v4-pro |\n| Moonshot (Kimi) | `MOONSHOT_API_KEY` | kimi-k2.6 |\n| OpenRouter | `OPENROUTER_API_KEY` | Any OpenRouter model |\n| Custom | `CUSTOM_API_URL` | Ollama, vLLM, LM Studio, etc. |\n\n## Quick start\n\n```bash\ngit clone https://github.com/linxule/vox-mcp.git\ncd vox-mcp\ncp .env.example .env\n# Edit .env — add at least one API key\nuv sync\nuv run python server.py\n```\n\n## MCP client configuration\n\nVox runs as a stdio MCP server. Each client needs to know how to launch it.\n\nReplace `/path/to/vox-mcp` with the absolute path to your cloned repo.\n\n### Claude Code (CLI)\n\n```bash\nclaude mcp add vox-mcp \\\n  -e GEMINI_API_KEY=your-key-here \\\n  -- uv run --directory /path/to/vox-mcp python server.py\n```\n\nOr add to `.mcp.json` in your project root:\n\n```json\n{\n  \"mcpServers\": {\n    \"vox-mcp\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"--directory\", \"/path/to/vox-mcp\", \"python\", \"server.py\"],\n      \"env\": {\n        \"GEMINI_API_KEY\": \"your-key-here\"\n      }\n    }\n  }\n}\n```\n\n### Claude Desktop\n\nAdd to `claude_desktop_config.json`:\n\n**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"vox-mcp\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"--directory\", \"/path/to/vox-mcp\", \"python\", \"server.py\"],\n      \"env\": {\n        \"GEMINI_API_KEY\": \"your-key-here\"\n      }\n    }\n  }\n}\n```\n\n### Cursor\n\nAdd to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):\n\n```json\n{\n  \"mcpServers\": {\n    \"vox-mcp\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"--directory\", \"/path/to/vox-mcp\", \"python\", \"server.py\"],\n      \"env\": {\n        \"GEMINI_API_KEY\": \"your-key-here\"\n      }\n    }\n  }\n}\n```\n\n### Windsurf\n\nAdd to `~/.codeium/windsurf/mcp_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"vox-mcp\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"--directory\", \"/path/to/vox-mcp\", \"python\", \"server.py\"],\n      \"env\": {\n        \"GEMINI_API_KEY\": \"your-key-here\"\n      }\n    }\n  }\n}\n```\n\n### Any MCP client\n\nThe canonical stdio configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"vox-mcp\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"--directory\", \"/path/to/vox-mcp\", \"python\", \"server.py\"],\n      \"env\": {\n        \"GEMINI_API_KEY\": \"your-key-here\"\n      }\n    }\n  }\n}\n```\n\n**Tips:**\n- Paths must be absolute\n- You only need one API key to start — add more providers later via `.env`\n- The `.env` file in the vox-mcp directory is loaded automatically, so API keys can go there instead of in the client config\n- Use `VOX_FORCE_ENV_OVERRIDE=true` in `.env` if client-passed env vars conflict with your `.env` values\n\n## Configuration\n\nCopy `.env.example` to `.env` and configure:\n\n- **API keys** — at least one provider key is required\n- **`DEFAULT_MODEL`** — `auto` (default, agent picks) or a specific model name\n- **Model restrictions** — `GOOGLE_ALLOWED_MODELS`, `OPENAI_ALLOWED_MODELS`, etc.\n- **`CONVERSATION_TIMEOUT_HOURS`** — thread TTL (default: 24h)\n- **`MAX_CONVERSATION_TURNS`** — thread length limit (default: 100)\n\nSee `.env.example` for the full reference.\n\n## Development\n\n```bash\nuv sync\nuv run python -c \"import server\"   # smoke test\nuv run pytest                       # run tests\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for code style, project structure, and how to add providers.\n\n## License\n\nApache 2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE).\n\nDerived from [pal-mcp-server](https://github.com/BeehiveInnovations/pal-mcp-server) by Beehive Innovations.\n\n<!-- mcp-name: io.github.linxule/vox-mcp -->\n",
  "bytes": 5229,
  "sha": "1594e0d81f879108526b87918c28e153219afd4d7c283814b0c076dd6677e211",
  "repo_slug": "linxule/vox-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_linxule_vox_mcp_aec1e33a/readme"
}