openai-compatible-mcp

A Model Context Protocol (MCP) server that bridges to any OpenAI-compatible chat API — DeepSeek, OpenAI, Azure OpenAI, OpenRouter, Together, Groq, local llama.cpp, and friends.

Default provider: DeepSeek. Switch to any OpenAI-compatible endpoint with a single environment variable. Version: v0.2.21 — see CHANGELOG.md for recent fixes.

The package ships two ways to integrate with MCP-aware clients:

The wizard at <http://127.0.0.1:8989> auto-detects which mode your client needs and writes the right config.

Quick start (Codex CLI / Claude / Cursor)

1. Install + start the wizard

pip install --upgrade openai-compatible-mcp
python -m openai_compatible_mcp

A browser opens at <http://127.0.0.1:8989>.

2. Pick provider, paste API key, click "Apply"

The wizard writes the right config for:

• Codex CLI → ~/.codex/config.toml (using direct API mode, no MCP sub-process)
• Claude Desktop → claude_desktop_config.json
• Cursor → ~/.cursor/mcp.json
• Claude Code → ~/.claude.json

…and does not overwrite any other servers you've configured.

3. Restart Codex / Claude

codex        # or restart Claude Desktop / Cursor

That's it.

Heads up — Codex 0.140+: the wizard uses provider id openai_compatible (not openai_compatible_mcp) because codex reserves the openai prefix for built-ins. If you have an older config from a pre-v0.2.21 wizard, the next "Apply" will auto-migrate it.

Integration modes

A. Direct API (recommended for Codex CLI 0.140+)

Wizard writes this into ~/.codex/config.toml:

# written by openai-compatible-mcp v0.2.21 (utf-8, no BOM)
model = "deepseek-v4-pro"
model_provider = "openai_compatible"

[projects.'c:\users\you']
trust_level = "trusted"

[windows]
sandbox = "elevated"

[model_providers.openai_compatible]
name = "OpenAI Compatible"
base_url = "http://127.0.0.1:7878/v1"
api_key = "sk-..."

Codex talks straight to the local proxy at http://127.0.0.1:7878/v1. No MCP sub-process, no 30-second startup timeout.

B. MCP server (for Claude Desktop, Cursor, etc.)

Wizard writes a [mcp_servers.X] block in your client config that launches python -m openai_compatible_mcp as a stdio child. The MCP server then opens its own HTTP listener for chat-completion calls.

{
  "mcpServers": {
    "openai-compatible": {
      "command": "python",
      "args": ["-m", "openai_compatible_mcp"],
      "env": { "DEEPSEEK_API_KEY": "sk-..." }
    }
  }
}

Architecture

┌──────────────────┐       stdio JSON-RPC        ┌─────────────────────┐
│ Claude Desktop   │ ───────────────────────────▶│                     │
│ Cursor / VSCode  │                             │ openai-compatible-  │
│ Claude Code      │                             │ mcp                 │
└──────────────────┘                             │                     │
                                                 │   ┌─────────────┐   │
┌──────────────────┐      HTTP /v1/chat/...      │   │ Proxy       │   │
│ Codex CLI 0.140+ │ ───────────────────────────▶│   │ 127.0.0.1   │   │
│ (direct API)     │                             │   │   :7878     │   │
└──────────────────┘                             │   └──────┬──────┘   │
                                                 │          │          │
┌──────────────────┐      http://127.0.0.1:8989  │          ▼          │
│ Your browser     │ ───────────────────────────▶│   Upstream API      │
│ (wizard UI)      │     one-time setup          │   (DeepSeek etc.)   │
└──────────────────┘                             └─────────────────────┘

• `python -m openai_compatible_mcp` starts both the wizard (port 8989) and

the local proxy (port 7878) in the same process.

• The wizard is for setup only — close it after writing config.
• The proxy is a long-running OpenAI-compatible endpoint — leave it running or

set up auto-start (the wizard offers this).

CLI install (no wizard)

git clone https://github.com/xiaobaotalks/openai-compatible-mcp.git
cd openai-compatible-mcp
pip install -e .

# Set your key
export DEEPSEEK_API_KEY="sk-..."   # or OPENAI_COMPATIBLE_MCP_API_KEY

# Smoke test
PYTHONPATH=src python tests/smoke_test.py

Environment variables

Features

• Zero third-party dependencies (Python 3.9+ stdlib only)
• Works with any OpenAI-compatible chat API
• Built-in wizard: 1 browser tab → 1 click → all clients configured
• Dual mode: MCP stdio and direct HTTP /v1/chat/completions
• Friendly model aliases (deepseek-v4-flash → deepseek-v4-flash, r1 → deepseek-reasoner)
• Optional reasoning content extraction (DeepSeek-R1 style)
• Tiny: ~2,000 lines of code

Tools (MCP mode)

chat

Send a chat completion to the configured provider.

Example:

{
  "method": "tools/call",
  "params": {
    "name": "chat",
    "arguments": {
      "messages": [
        {"role": "user", "content": "Write a haiku about Python."}
      ],
      "model": "deepseek-v4-flash",
      "temperature": 0.7
    }
  }
}

list_models

Returns the default model and the alias table.

Built-in model aliases

Any name not in the table is passed through unchanged.

Recent fixes (v0.2.13 → v0.2.21)

The wizard has gone through several bug fixes in the past week. If you have an older version, upgrading and re-applying the wizard is the fastest way out of most "Codex says invalid TOML" or "wizard won't start" problems.

See CHANGELOG.md for the full history.

Development

python -m venv .venv
.venv\Scripts\activate       # Windows
source .venv/bin/activate    # macOS / Linux
pip install -e ".[dev]"
PYTHONPATH=src python tests/smoke_test.py

License

MIT — see LICENSE.