opencode MCP server

A small, dependency-light MCP (stdio) server that lets Claude Code delegate cheap, mechanical work to opencode's free models — codebase summaries, exploration, web research, boilerplate, first drafts, contained bulk edits — so paid tokens go where they matter.

Python 3.10+, stdlib + the official mcp SDK. Runs on Linux and Windows.

Tools

Tool	Purpose
delegate	Run one task on a free model. mode:"read" (default) is enforced read-only; mode:"write" may edit files under dir. Supports named sessions (multi-turn), file attachments, per-call model/timeout, and opencode_config to hand the worker extra MCP servers.
list_sessions	Named sessions with opencode ids, dirs, turn counts, token/cost tallies.
forget_session	Drop a name from local bookkeeping (opencode's server-side session survives).
ping	Liveness + doctor: resolves the binary, reports version, round-trips one prompt.
models	List model ids (free only by default — free ids rotate).

Safety model

The worker is a cheap model; the guardrails assume it will occasionally do something dumb.

• Read-only by default. mode:"read" maps to opencode --agent plan. Verified behavior: file writes and bash mutations are refused (nothing ever hit disk in testing); read-only shell commands and network (websearch) still work — read mode is not offline.
• Write mode is confined. dir must be an absolute, existing directory; the filesystem root, the home directory itself, and system paths (/etc, /usr, /var, …, C:\Windows, C:\Program Files*) are refused, including their subtrees. Optionally set OPENCODE_MCP_ALLOWED_DIRS (pathsep-separated roots) to allowlist where write mode may operate.
• Never --auto. opencode's own permission prompts stay denied in non-interactive runs.
• Everything is reported. files_changed and tools_used come back on every call; point write mode at git-tracked dirs so you can diff/revert.
• Hard timeout with tree-kill (opencode spawns child processes): POSIX process-group kill, Windows taskkill /T /F. Cancelling the MCP call kills the worker too. Timeouts return partial results and keep the session resumable.
• One call per session name at a time; parallel calls on different sessions are fine.

Install & register

cd /root/agent-mcp
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

# register with Claude Code (user scope):
claude mcp add -s user opencode -- /root/agent-mcp/.venv/bin/python /root/agent-mcp/server.py

Windows (PowerShell):

cd C:\path\to\agent-mcp
py -3 -m venv .venv
.venv\Scripts\pip install -r requirements.txt
claude mcp add -s user opencode -- C:\path\to\agent-mcp\.venv\Scripts\python.exe C:\path\to\agent-mcp\server.py

Windows smoke check (3 commands):

opencode --version                                  # CLI reachable?
.venv\Scripts\python -m unittest discover -s tests  # parser/guards/kill-path
.venv\Scripts\python tests\e2e_client.py            # live free-model round-trip

Configuration (env vars, all optional)

Var	Default	Meaning
OPENCODE_MCP_BIN	auto-detect	Path to the opencode executable. Auto-detection: PATH, then the real opencode.exe behind npm .cmd shims on Windows, then ~/.opencode/bin/opencode.
OPENCODE_MCP_MODEL	opencode/deepseek-v4-flash-free	Default model id.
OPENCODE_MCP_STATE	~/.local/state/opencode-mcp / %LOCALAPPDATA%\opencode-mcp	Where sessions.json lives.
OPENCODE_MCP_TIMEOUT	180	Default per-call timeout (s); per-call timeout_sec clamps to 10–570.
OPENCODE_MCP_MAX_TEXT	40000	Truncate the worker's answer beyond this many chars (truncated: true).
OPENCODE_MCP_ALLOWED_DIRS	unset	If set, write-mode dir must live under one of these roots.

Giving the worker MCP tools

Pass opencode_config (absolute path) to delegate, pointing at e.g.:

{
  "mcp": {
    "gbk-fs": {
      "type": "local",
      "command": ["/root/gbk-fs/.venv/bin/python3", "-m", "gbk_fs"],
      "enabled": true
    }
  }
}

Verified live: the free model discovers and calls such tools (they surface to it as gbk-fs_list_files, etc.).

Tests

.venv/bin/python -m unittest discover -s tests   # offline: real captured fixtures
.venv/bin/python tests/e2e_client.py             # live: needs network, ~1-2 min, $0

Design notes / gotchas (hard-won)

• The task prompt is piped via stdin (write, close). Never pass it in argv: a -- separator makes opencode drop the message and hang waiting on stdin, and Windows caps argv at 32 KB.
• Resume sessions with -s <ses_id> (never --continue).
• opencode run --format json emits JSONL events; the answer is the concatenation of text parts, tokens/cost arrive in step-finish parts, file writes are completed tool parts (write/edit/patch/multiedit) with state.input.filePath.
• Pipes are forced to UTF-8 (errors="replace") — Windows would otherwise default to cp125x. stderr goes to a temp file to avoid two-pipe deadlock.
• Free model ids rotate; the models tool exists so the orchestrator can self-correct when the default disappears.