Codex to OpenCode MCP Server

A small local MCP (Model Context Protocol) server that lets Codex delegate coding work to OpenCode. It uses the official MCP Python SDK, the stdio transport, and an asynchronous OpenCode subprocess.

Tools

opencode_execute

opencode_execute(
    task: str,
    working_directory: str,
    model: str | None = None,
    reasoning_effort: str | None = None,
    timeout: int = 1800,
)

Runs this command without a shell:

opencode run --format json --dir <working_directory> --auto [--model <model>] [--variant <reasoning_effort>] <task>

reasoning_effort maps to OpenCode's provider-specific --variant option. Common values include minimal, low, medium, high, and max, but the available variants are defined by the selected provider and model. The MCP server intentionally accepts any non-empty value instead of enforcing a provider-specific enum.

Example:

opencode_execute(
    task="Implement uncertainty propagation and run the unit tests.",
    working_directory="C:\\path\\to\\NuSR",
    model="pinche_10/gpt-5.6-sol",
    reasoning_effort="high",
    timeout=1800,
)

It returns structured output containing:

• success, timeout, exit code, and elapsed time;
• OpenCode session ID and final assistant summary;
• completed OpenCode tool calls and errors;
• bounded stdout/stderr captures;
• final git status --short, git diff --stat, and a bounded unified diff.

The Git fields are post-run snapshots. They can include changes that were already present before the call. Text contents of untracked files are represented as new-file patches; binary untracked files are reported by path and size.

opencode_check

Resolves the configured OpenCode executable and runs opencode --version without modifying the environment.

Install

Requirements: Python 3.11+, Git (optional for diff reporting), and OpenCode.

git clone https://github.com/TAO-MINGYU/codex_to_opencode.git
cd codex_to_opencode
uv venv --python 3.11 .venv
uv pip install --python .venv\Scripts\python.exe -e ".[dev]"

OpenCode must be installed and authenticated independently. Verify it first:

opencode --version
opencode auth list

The OpenCode desktop application and the OpenCode CLI are separate entry points on Windows. An OpenCode.exe --version invocation that opens the GUI and prints nothing is not a usable CLI. Install the official CLI when needed:

npm install -g opencode-ai

If opencode is not in PATH, set OPENCODE_MCP_COMMAND to its absolute executable path. On Windows npm installations, prefer the native binary under node_modules\opencode-ai\bin\opencode.exe; the server also detects and bypasses the opencode.cmd wrapper automatically.

Connect Codex

Add the server through the Codex CLI, which avoids hand-editing configuration:

codex mcp add opencode --env OPENCODE_MCP_COMMAND=C:\path\to\opencode.exe -- C:\path\to\opencode-mcp\.venv\Scripts\python.exe -m opencode_mcp.server

When OpenCode is already in PATH, omit the --env option:

codex mcp add opencode -- C:\path\to\opencode-mcp\.venv\Scripts\python.exe -m opencode_mcp.server

Then verify registration:

codex mcp list

Restart Codex after changing MCP configuration. The server writes protocol messages only to stdout and sends logs to stderr, as required for stdio MCP servers.

Configuration

Environment variable	Default	Meaning
OPENCODE_MCP_COMMAND	opencode	Executable name or absolute path
OPENCODE_MCP_ARGS	[]	JSON array inserted after the executable (useful for wrappers/tests)
OPENCODE_MCP_AUTO_APPROVE	true	Add OpenCode's --auto permission flag
OPENCODE_MCP_MAX_OUTPUT_BYTES	2097152	Tail bytes retained independently for stdout/stderr
OPENCODE_MCP_LOG_LEVEL	INFO	Server log level written to stderr

Setting auto-approval to false makes OpenCode reject permissions it cannot ask interactively:

$env:OPENCODE_MCP_AUTO_APPROVE = "false"

Debug

Run the automated tests:

.venv\Scripts\python.exe -m pytest --cov=opencode_mcp --cov-fail-under=80
.venv\Scripts\python.exe -m ruff check .
.venv\Scripts\python.exe -m ruff format --check .

Run the server under MCP Inspector:

uv run --python 3.11 --with-editable ".[dev]" mcp dev src\opencode_mcp\server.py

The MCP tool timeout should be slightly longer than the timeout passed to opencode_execute; otherwise Codex may cancel the MCP request before the server can terminate OpenCode and return diagnostics.

Security model

opencode_execute is intentionally a write-capable, potentially destructive tool. It grants OpenCode the same filesystem and process permissions as this MCP server. The implementation:

• never invokes a shell for OpenCode tasks;
• requires an existing absolute working-directory path;
• bounds captured output to protect Codex context;
• terminates the OpenCode process tree on timeout or MCP cancellation;
• disables OpenCode auto-update during delegated runs;
• marks the MCP tool as non-idempotent and potentially destructive.

Use a restricted OS account or sandbox when delegating untrusted tasks or repositories.