opencode-mcp

An MCP (Model Context Protocol) server that lets any MCP host — Claude Code, Codex, Cursor, etc. — drive an OpenCode instance and delegate work to its subagents — so orchestrator models like Opus or Fable can hand off tasks to the other models OpenCode exposes.

Quick install

Requires Node.js 18+ and OpenCode 1.x installed and configured (opencode must be on your PATH, with at least one provider/model set up) — this server spawns and drives OpenCode instances.

For Claude Code:

claude mcp add opencode -- npx -y mcp-server-opencode

For Codex:

codex mcp add opencode -- npx -y mcp-server-opencode

See Installation for manual config, and from-source options.

Tools

Delegation workflow and model-selection guidance are provided through the MCP server instructions.

How it works

Task delegation is asynchronous: opencode_start_task returns a task_id and run_id without waiting, so hosts can start tasks in parallel. Tasks use the selected directory by default; managed Git worktrees are optional. Poll for status and retrieve results separately. If dispatch is uncertain, use the returned IDs to check or cancel the task instead of retrying it.

Execution reports and caller checks

Start and continuation calls can include expected_changes and checks. Status and result responses report workspace changes, verification, diagnostics, and evidence; pass a run_id to retrieve a historical run. Workspace changes are best-effort evidence, since concurrent writers can make attribution uncertain.

Shared directories and managed worktrees

Tasks run in the selected existing directory (shared, the default), or in an isolated managed Git worktree based on a commit. Worktrees are kept after execution; use opencode_cleanup_workspace with its workspace_id after reports are finalized. Cleanup only removes worktrees managed by this server, and dirty worktrees require explicit discard.

Usage reporting

Status, wait, and result responses include run and session usage snapshots, with metrics broken down by provider and model. Missing metrics remain unknown rather than zero, and cost is OpenCode-reported—not an invoice total. Finalized runs retain their snapshots for historical retrieval.

Task history and workspace ownership are held in memory for the lifetime of the MCP process. Restarting loses these records; retained worktrees are not automatically rediscovered.

Installation

Prerequisites

• Node.js 18+
• OpenCode 1.x installed and configured (opencode must be on your PATH, with at least one provider/model set up) — this server spawns and drives OpenCode instances.

The current adapter uses the OpenCode v1 SDK/API and was validated against OpenCode 1.18.34. OpenCode 2.x is not yet supported.

Option 1 — npm (recommended)

The package is published as mcp-server-opencode. No cloning or building needed — point your MCP host at npx:

For Claude Code, one command does it:

claude mcp add opencode -- npx -y mcp-server-opencode

Or manually

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

For Codex, add the server to ~/.codex/config.toml:

[mcp_servers.opencode]
command = "npx"
args = ["-y", "mcp-server-opencode"]

Or install it globally and use the binary directly:

npm install -g mcp-server-opencode

{
  "mcpServers": {
    "opencode": {
      "command": "opencode-mcp"
    }
  }
}

Option 2 — from source

git clone https://github.com/alejandro-technology/opencode-mcp.git
cd opencode-mcp
pnpm install
pnpm build

Then point your MCP host at the built entrypoint:

{
  "mcpServers": {
    "opencode": {
      "command": "node",
      "args": ["/path/to/opencode-mcp/build/src/index.js"]
    }
  }
}

Restart your MCP host after editing the config; the opencode_* tools should appear in its tool list.

Configuration

MCP_TOOL_TIMEOUT

opencode_wait_for_task accepts a timeout_ms input, but it's clamped to a server-side maximum so a single call can't block the MCP connection indefinitely. That maximum defaults to 300000 ms (5 minutes) and is configurable via MCP_TOOL_TIMEOUT.

MCP_TOOL_TIMEOUT can be set two ways:

• Environment variable — set it in the MCP server config:

  {
    "mcpServers": {
      "opencode": {
        "command": "node",
        "args": ["/path/to/opencode-mcp/build/src/index.js"],
        "env": { "MCP_TOOL_TIMEOUT": "1200000" }
      }
    }
  }
  

• CLI argument — pass MCP_TOOL_TIMEOUT=<ms> as an extra arg to the server process:

  {
    "mcpServers": {
      "opencode": {
        "command": "node",
        "args": [
          "/path/to/opencode-mcp/build/src/index.js",
          "MCP_TOOL_TIMEOUT=1200000"
        ]
      }
    }
  }
  

If both are present, the environment variable takes precedence over the CLI argument. Invalid or non-numeric values fall back to the 300000 ms default.

Permissions and trust

Headless tasks automatically answer permission prompts. Set OPENCODE_MCP_EXTERNAL_DIR to read-only (default), allow, or deny to control external-directory requests. An environment variable takes precedence over an OPENCODE_MCP_EXTERNAL_DIR=<policy> CLI argument; explicit OpenCode deny rules remain in effect.

Use this server only with trusted hosts and repositories. Git worktrees isolate source changes, not OS permissions: agents and caller-provided checks run as your local user, not in a security sandbox.

Development

Project structure

src/
├── index.ts                   # MCP server entrypoint (stdio transport, shutdown handlers)
└── modules/
    ├── tools/                 # One file per MCP tool, registered in index.ts
    └── shared/                # Cross-tool infrastructure (selected modules below)
        ├── server-registry.ts   # Tracks running OpenCode servers
        ├── task-registry.ts     # Task/session identity and per-run history
        ├── opencode-client.ts   # SDK clients, status derivation, and progress
        ├── run-observer.ts      # Background run finalization and result caching
        ├── execution-report.ts  # Workspace evidence and executable checks
        ├── execution-usage.ts   # Run/session usage aggregation
        ├── workspace-manager.ts # Managed Git worktree lifecycle
        ├── permissions.ts       # Headless permission decisions and responses
        ├── instructions.ts      # Delegation workflow and model-selection guidance
        ├── config.ts            # MCP_TOOL_TIMEOUT resolution
        └── mcp-result.ts        # JSON tool result helpers

Each module ships with a *.test.ts Vitest suite under the parallel tests/ tree mirroring src/.

Getting started

Use Node.js 22.18+ for development and smoke tests (native TypeScript execution); CI checks Node.js 22 and 24. The published server retains its Node.js 18+ runtime requirement.

pnpm install
pnpm dev     # runs the server through the MCP Inspector (tsx, no build needed)

Other scripts:

pnpm test           # vitest run
pnpm test:coverage  # vitest run --coverage
pnpm lint           # biome check
pnpm lint:write     # biome check --write
pnpm build          # clean tsc build to ./build (also the source typecheck)

Real OpenCode smoke tests

The opt-in smoke harness starts a real OpenCode server and removes its temporary fixtures afterward. It is not part of default CI.

pnpm smoke --message-id-only   # non-billable message-ID contract probe
pnpm smoke                     # full smoke; requires credentials and may incur model charges

The full smoke covers reports, usage, continuation, cancellation, isolated worktrees, and cleanup. Its default model is openai/gpt-6-luna; override it with an exact enabled model ID:

OPENCODE_MCP_SMOKE_MODEL=provider/model pnpm smoke