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** 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

How it works

Task delegation is asynchronous: starting a task returns immediately with a `task_id` instead of blocking until the subagent finishes. This lets Claude Code fire multiple `opencode_start_task` calls in parallel — each one opens an isolated OpenCode `Session` — without hitting MCP client timeouts on long-running work. Status and results are fetched separately via polling.

Installation

Prerequisites

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

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=` 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.

Development

Project structure

src/
├── index.ts                   # MCP server entrypoint (stdio transport, shutdown handlers)
└── modules/
    ├── tools/                 # One file per MCP tool, registered in index.ts
    ├── prompts/               # One file per MCP prompt, registered in index.ts
    └── shared/                # Cross-tool infrastructure
        ├── server-registry.ts   # Tracks running OpenCode servers; killAllServers() on shutdown
        ├── task-registry.ts     # Maps task_id → OpenCode server + session
        ├── opencode-client.ts   # Builds SDK clients from the registries
        ├── config.ts            # MCP_TOOL_TIMEOUT resolution (env var / CLI arg)
        └── mcp-result.ts        # jsonResult / jsonError MCP output helpers

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

Getting started

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 typecheck)