opencode-bridge-mcp

Local MCP bridge that lets coordinator agents (Claude Code, Codex, etc.) delegate low-cost text work and long-running shell tasks to the OpenCode CLI.

Requirements

• Node.js 20+
• OpenCode CLI installed and authenticated (opencode auth login)

Use without installing

npx opencode-bridge-mcp

The bundled bridge-worker opencode agent is loaded automatically via OPENCODE_CONFIG, so the bridge works from any cwd.

Install globally

npm install -g opencode-bridge-mcp
opencode-bridge-mcp

Coordinator integration

Claude Code

Add to .mcp.json (project) or ~/.claude.json:

{
  "mcpServers": {
    "opencode-bridge": {
      "command": "npx",
      "args": ["-y", "opencode-bridge-mcp"]
    }
  }
}

Tools appear as mcp__opencode-bridge__opencode_summarize etc.

Codex CLI

codex mcp add opencode-bridge -- npx -y opencode-bridge-mcp

Tools appear as opencode-bridge/opencode_summarize etc. Verify with codex mcp list.

Tools

• opencode_summarize — synchronous text summarization
• opencode_read_and_analyze — read files in a workdir and return lightweight analysis
• opencode_run_long_task — kick off long shell-oriented work, returns a task_id
• opencode_get_task_status — poll background task status
• opencode_get_task_result — fetch reduced final result (summary, key findings, log tail)

Long-running tasks store metadata, logs, and reduced results under ./data/tasks/<task_id>/ in the cwd of the bridge process (override with OPENCODE_MCP_BRIDGE_TASKS_DIR).

Environment variables

• OPENCODE_BIN — path to the OpenCode binary (default: opencode)
• OPENCODE_AGENT — agent name (default: bridge-worker, bundled with the package)
• OPENCODE_ATTACH_URL — URL of a running opencode serve instance (avoids cold start)
• OPENCODE_MODEL — provider/model override for OpenCode runs
• OPENCODE_CONFIG — full path to an opencode config file. Defaults to the bundled config; override only if you want to inject a different agent definition.
• OPENCODE_MCP_BRIDGE_TASKS_DIR — task storage directory (default: ./data/tasks)
• OPENCODE_MCP_BRIDGE_LOG_TAIL_LINES — log lines returned in reduced task results (default: 20)
• OPENCODE_MCP_BRIDGE_PACKAGE_ROOT — override the package root used to locate the bundled opencode.json and prompts/. Rarely needed.

Warm OpenCode backend

Reduce cold starts by running OpenCode in serve mode:

opencode serve
export OPENCODE_ATTACH_URL=http://localhost:4096

Development

pnpm install
pnpm check    # build + tests
pnpm dev      # run from source