Skip to main content
Glama
README.md
# opencode-mcp-server

An MCP server that exposes a running **OpenCode v2** instance to any MCP client — Codex, Claude Code,
Claude Desktop, Anti-Gravity, Cursor, or your own agent. Sessions, inference, agents, files, MCP
servers and history all become tools in the client's chat.

The bridge does not reimplement anything: it translates MCP tool calls into OpenCode v2 API calls
through the official `@opencode/client` SDK.

```
Codex / Claude / Anti-Gravity  ──MCP──▶  opencode-mcp-server  ──@opencode/client──▶  OpenCode v2 (:4096)
```

## Requirements

- Node.js ≥ 20
- A running OpenCode **v2** server (`opencode serve`, or the TUI) — v1 is rejected on purpose
- The server address and password (username is always `opencode`)

## Setup

The bridge needs two values:

```
OPENCODE_URL       e.g. http://127.0.0.1:4096
OPENCODE_PASSWORD  the OpenCode Basic-auth password
```

Find the password in `~/.config/opencode/service.json` (or `~/.local/state/opencode/service.json`).

### Install / run

No npm release required — this runs straight from GitHub:

```sh
npx -y github:shivrajansingh/opencode-mcp-server --help
```

Pin to a release or commit for stability: `github:shivrajansingh/opencode-mcp-server#v0.1.0`.

### Option A — configure once, from the terminal

```sh
npx -y github:shivrajansingh/opencode-mcp-server configure --url http://127.0.0.1:4096
# prompts for the password without echoing it, validates it, writes ~/.config/opencode-mcp/config.json (0600)
```

Check it:

```sh
npx -y github:shivrajansingh/opencode-mcp-server status
```

### Option B — configure in the MCP client

```toml
# ~/.codex/config.toml
[mcp_servers.opencode]
command = "npx"
args = ["-y", "github:shivrajansingh/opencode-mcp-server"]
env = { OPENCODE_URL = "http://127.0.0.1:4096", OPENCODE_PASSWORD = "…" }
```

```sh
# Claude Code
claude mcp add opencode -e OPENCODE_URL=http://127.0.0.1:4096 -e OPENCODE_PASSWORD=… \
  -- npx -y github:shivrajansingh/opencode-mcp-server
```

```json
// Claude Desktop / Anti-Gravity MCP config
{
  "mcpServers": {
    "opencode": {
      "command": "npx",
      "args": ["-y", "github:shivrajansingh/opencode-mcp-server"],
      "env": { "OPENCODE_URL": "http://127.0.0.1:4096", "OPENCODE_PASSWORD": "…" }
    }
  }
}
```

### Option C — configure from the chat

Start the server with no credentials. It still lists its tools and `opencode_status` explains what is
missing. Then ask the model to call:

```json
opencode_configure({ "url": "http://127.0.0.1:4096", "password": "…" })
```

Values are validated before they are applied, the password is never echoed, and nothing is written to
disk unless you pass `persist: true`.

### Precedence

`runtime (opencode_configure)` → `environment` → `~/.config/opencode-mcp/config.json` → unconfigured.
There is no silent auto-discovery; `--discover` exists for development only.

## Tools (18)

| Tool | What it does |
|---|---|
| `opencode_status` | Health, version, workspace, agents, default model. Works while unconfigured. |
| `opencode_configure` | Validate and apply URL + password in-chat. |
| `opencode_workspace` | Show/persist the working directory, list MCP roots. |
| `opencode_session_create` | New session in a directory (agent, model, parent, permissions). |
| `opencode_session_list` | List sessions by directory/search/archive/parent. |
| `opencode_session_get` | Session metadata, tokens, cost. |
| `opencode_session_move` | Change a session's directory. |
| `opencode_session_delete` | Delete a session. |
| `opencode_session_interrupt` | Stop the current run. |
| `opencode_session_compact` | Summarize history to free context. |
| `opencode_session_prompt` | Prompt with text + files, wait for the answer, return tools/usage. |
| `opencode_session_history` | Messages as JSON or markdown transcript. |
| `opencode_model` | List models, read the default, assign at session/project/global/agent scope. |
| `opencode_agent` | List agents, switch agent, delegate to a subagent. |
| `opencode_task` | One-shot delegation: create session → prompt → wait → return transcript. |
| `opencode_file_attach` | Attach a path or base64 bytes to a session (optionally prompt immediately). |
| `opencode_mcp` | Inspect/add/connect/remove OpenCode's own MCP servers. |
| `opencode_permission` | List/reply to permission requests (required for headless runs). |

`--profile minimal` registers 9 tools: status, configure, workspace, session create/prompt/history,
model, task, permission.

## Model assignment

Four levels, all through `opencode_model`:

| Scope | Call | Effect | Storage |
|---|---|---|---|
| **Session** | `{ action:"set", sessionID, model }` | immediate switch for that conversation | OpenCode DB |
| **Project** | `{ action:"set", scope:"project", directory, model }` | default for new sessions in that workspace | `opencode.json` (comments preserved) |
| **Global** | `{ action:"set", scope:"global", model }` | default everywhere | `~/.config/opencode/opencode.json` |
| **Agent** | `{ action:"set", scope:"agent", agent:"build", model }` | model for that agent's runs | `agents.<id>.model` in the nearest config |

Precedence: session → agent → project → global. `scope` defaults to `session` when `sessionID` is
given, otherwise `project`.

Project/global writes use a JSONC-aware editor (comments and unrelated keys survive), then trigger an
OpenCode config reload and verify the result against `model/default`. Agent-level writes are verified
by reading the file back, because OpenCode does not expose the resolved per-agent model through the
API.

```jsonc
// opencode.json
{
  "model": { "providerID": "opencode", "model": "iceman-free" },
  "agents": { "build": { "model": { "providerID": "opencode", "model": "inkling-2-small-free" } } }
}
```

A model can also be passed at creation time: `opencode_session_create({ model: { providerID, id, variant? } })`.

## How a client actually runs OpenCode

There are two entry points, both of which hand real work to OpenCode:

**1. Persistent session** — the chat keeps going:

```js
opencode_session_create({ directory })
opencode_session_prompt({ sessionID, text: "Fix the failing test in src/auth.ts" })
// → OpenCode's own agent (build) runs the model, edits files, runs commands, and returns the answer
```

**2. One-shot delegation** — "do this task and give me the result":

```js
opencode_task({
  directory: "/repo",
  agent: "build",            // or plan / general / explore
  prompt: "Create hello.txt with 'hello from opencode', then cat it",
  timeoutMs: 250000
})
```

`opencode_task` creates the session, sends the prompt, waits for the run to finish, and returns the
assistant text, every tool call (`write`, `shell`, …), token/cost usage, and the child `sessionID`.
Subagents work the same way: pass `agent: "explore"` or `parentSessionID` to attach the run as a child.

The MCP client never touches the model. It sends text; OpenCode does inference through its own
providers, runs the agentic loop with its own tools and permissions, and the bridge only translates
the request/response. That means the client gets OpenCode's tools, MCP servers, skills, and models
for free.

If OpenCode asks for permission mid-run, the run blocks; use `opencode_permission { action: "list" }`
and `{ action: "reply" }` to approve or reject headlessly.

**Verified end to end:** `npm run agentic-smoke` asks the `build` agent to write a file and run
`cat`, then asserts the file exists on disk with the right content and that `write` + `shell` appear
in the transcript.

## Workspace resolution

Sessions are created in, in order: the tool's `directory` argument → MCP `roots` → `CLAUDE_PROJECT_DIR` /
`OPENCODE_MCP_DIRECTORY` / `INIT_CWD` → configured `defaultDirectory` → process cwd. The home directory
and `/` are never used as a silent fallback; the bridge returns an actionable error instead.

## HTTP transport

```sh
OPENCODE_MCP_TOKEN=… npx opencode-mcp-server --http --port 7777
# POST http://127.0.0.1:7777/mcp  with  Authorization: Bearer <token>
```

If `OPENCODE_MCP_TOKEN` is unset, a token is generated at `~/.config/opencode-mcp/http-token` (0600).
Health check: `GET /healthz`. The same token protects a settings endpoint:

```sh
curl -X POST http://127.0.0.1:7777/configure \
  -H "Authorization: Bearer $OPENCODE_MCP_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"url":"http://127.0.0.1:4096","password":"…"}'
```

## Security notes

- The bridge can run an agent with shell access — treat it as remote code execution by design.
- Loopback binding, bearer token, and loopback-only OpenCode URLs by default.
- `--read-only` disables prompts, compaction, deletes, moves, uploads and permission replies.
- `allowedRoots` (config file or `OPENCODE_MCP_ALLOWED_ROOTS`) blocks path escapes, symlink-safe.
- Passwords never appear in logs, errors, or tool output; the audit-friendly paths redact them.
- `opencode_configure` cannot change `allowedRoots` or the permission profile.

## Development

```sh
npm install
npm run typecheck
npm test              # unit tests (vitest)
npm run build
OPENCODE_URL=… OPENCODE_PASSWORD=… npm run smoke   # live end-to-end (stdio)
node scripts/http-smoke.mjs                        # live end-to-end (HTTP, after starting --http)
```

## Status

Working: all 18 tools, stdio + HTTP transports, config/status/configure, workspace resolution,
model assignment at session/project/global/agent scope, attachments, delegation, compaction,
permissions, MCP administration.

Not yet implemented from `docs/plan.md`: audit log file, OS keychain storage, artifact resources
(`opencode://…`), progress notifications, and per-client smoke tests against Codex/Anti-Gravity.

TDQS

B3.4/5.0

Scored across 18 tools

Disambiguation3/5

Session-level tools are clearly separable, but three tools converge on one-shot delegation: opencode_task, opencode_agent (delegate action), and opencode_session_prompt with wait=false all fire a prompt and return an answer. opencode_file_attach with `text` also silently turns into a prompt, and opencode_session_move overlaps conceptually with opencode_workspace. The descriptions do offer cross-references ('use opencode_session_* for persistent conversations'), which keeps it workable but not clean.

Naming Consistency3/5

There is a solid opencode_session_<verb> sub-family (create, prompt, list, get, move, delete, interrupt, compact, history), but the remaining ten tools are bare nouns (opencode_status, opencode_workspace, opencode_agent, opencode_model, opencode_task, opencode_mcp) or noun-first (opencode_file_attach). The shared opencode_ prefix keeps things scannable, but the verb placement convention flips between families.

Tool Count4/5

Eighteen tools is on the heavy side but the surface genuinely spans several sub-domains: session lifecycle, config/credentials, workspace, models, agents, permissions, files, and MCP management. Session operations account for nine of them, which is defensible for a chat-oriented bridge, though a couple (compact, move) feel like lower-frequency add-ons.

Completeness4/5

The session lifecycle is essentially fully covered (create/list/get/prompt/history/interrupt/compact/move/delete), plus config, model assignment, permissions, and file attachment. Minor gaps: sessions can be filtered by archive state but there is no tool to archive or rename/retitle a session, and there is no message-level retry or edit operation. These are workarounds-possible rather than blocking.

Maintenance

ActivityMaintained
ResponsivenessOutdated data