@mekareteriker/opencode-mcp

This is a hardened fork of AlaeddineMessadi/opencode-mcp. The upstream package is unmaintained on npm (latest release v1.10.1 is 5+ weeks old and missing a Windows-blocking fix already merged on master). This fork re-publishes upstream main HEAD, adds CI for Linux/Windows/macOS, and ships further hardening — structured errors, idempotency, SSE streaming — on a regular release cadence. Drop-in replacement: same wire protocol, same 79 tools.

Patches pending upstream are tracked in CHANGELOG.md and submitted upstream as PRs. When upstream merges, we rebase and the patch leaves the fork. We aim to stay as close to upstream as possible.

Give any MCP client the power of OpenCode.

opencode-mcp is an MCP server that bridges your AI tools (Claude, Cursor, Windsurf, VS Code, etc.) to OpenCode's headless API. It lets your AI delegate real coding work — building features, debugging, refactoring, running tests — to OpenCode sessions that autonomously read, write, and execute code in your project.

79 tools | 10 resources | 6 prompts | Multi-project | Auto-start | Windows-tested

Why Use This?

• Delegate coding tasks — Tell Claude "build me a REST API" and it delegates to OpenCode, which creates files, installs packages, writes tests, and reports back.
• Parallel work — Fire off multiple tasks to OpenCode while your primary AI keeps working on something else.
• Any MCP client — Works with Claude Desktop, Claude Code, Cursor, Windsurf, VS Code Copilot, Cline, Continue, Zed, Amazon Q, and any other MCP-compatible tool.
• Zero setup — The server auto-starts opencode serve if it's not already running. No manual steps.
• Windows-first CI — Every release is tested on Linux, Windows, and macOS across Node 18/20/22.

Quick Start

Prerequisite: OpenCode must be installed. curl -fsSL https://opencode.ai/install | bash or npm i -g opencode-ai or brew install sst/tap/opencode

Claude Code:

claude mcp add opencode -- npx -y @mekareteriker/opencode-mcp

Claude Desktop / Cursor / Windsurf / Cline / Continue (add to your MCP config):

{
  "mcpServers": {
    "opencode": {
      "command": "npx",
      "args": ["-y", "@mekareteriker/opencode-mcp"]
    }
  }
}

That's it. Restart your client and OpenCode's tools will be available.

Migrating from upstream opencode-mcp

If you have the upstream package in your MCP config, change "opencode-mcp" to "@mekareteriker/opencode-mcp" in the args array. Nothing else changes — same tool names, same parameters, same behavior. To go back, just swap the name back.

See Configuration for all client configs (VS Code Copilot, Zed, Amazon Q, etc.) and environment variables.

How It Works

MCP Client  <--stdio-->  opencode-mcp  <--HTTP-->  OpenCode Server
(Claude, Cursor, etc.)   (this package)            (opencode serve)

Your MCP client calls tools over stdio. This server translates them into HTTP requests to the OpenCode headless API. If the OpenCode server isn't running, it's started automatically.

Key Tools

The 79 tools are organized into tiers. Start with the workflow tools — they handle the common patterns in a single call.

Workflow Tools (13) — Start Here

| Tool | What it does | |---|---| | opencode_setup | Check server health, providers, and project status. Use first. | | opencode_ask | Create session + send prompt + get answer. One call. | | opencode_reply | Follow-up message in an existing session | | opencode_run | Send a task and wait for completion (session + async send + polling) | | opencode_fire | Fire-and-forget: dispatch a task, return immediately | | opencode_check | Compact progress report for a running session (status, todos, files changed) | | opencode_conversation | Get formatted conversation history | | opencode_sessions_overview | Quick overview of all sessions | | opencode_context | Project + VCS + config + agents in one call | | opencode_review_changes | Formatted diff summary for a session | | opencode_wait | Poll an async session until it finishes | | opencode_provider_test | Quick-test whether a provider is working | | opencode_status | Health + providers + sessions + VCS dashboard |

Recommended Patterns

Quick question:

opencode_ask({ prompt: "Explain the auth flow in this project" })

Build something and wait:

opencode_run({ prompt: "Add input validation to POST /api/users", maxDurationSeconds: 300 })

Parallel background tasks:

opencode_fire({ prompt: "Refactor the auth module to use JWT" })
→ returns sessionId immediately
opencode_check({ sessionId: "..." })
→ check progress anytime

All Tool Categories

| Category | Count | Description | |---|---|---| | Workflow | 13 | High-level composite operations | | Session | 20 | Create, list, fork, share, abort, revert, permissions | | Message | 6 | Send prompts, execute commands, run shell | | File & Search | 6 | Search text/regex, find files/symbols, read files | | System | 13 | Health, VCS, LSP, MCP servers, agents, logging | | TUI Control | 9 | Remote-control the OpenCode terminal UI | | Provider & Auth | 6 | List providers/models, set API keys, OAuth | | Config | 3 | Get/update configuration | | Project | 2 | List and inspect projects | | Events | 1 | Poll real-time SSE events |

Resources (10)

Browseable data endpoints — your client can read these without tool calls:

| URI | Description | |---|---| | opencode://project/current | Current active project | | opencode://config | Current configuration | | opencode://providers | Providers with models | | opencode://agents | Available agents | | opencode://commands | Available commands | | opencode://health | Server health and version | | opencode://vcs | Version control info | | opencode://sessions | All sessions | | opencode://mcp-servers | MCP server status | | opencode://file-status | VCS file status |

Prompts (6)

Guided workflow templates your client can offer as selectable actions:

| Prompt | Description | |---|---| | opencode-code-review | Review diffs from a session | | opencode-debug | Step-by-step debugging workflow | | opencode-project-setup | Get oriented in a new project | | opencode-implement | Have OpenCode build a feature | | opencode-best-practices | Setup, tool selection, monitoring, and pitfalls | | opencode-session-summary | Summarize what happened in a session |

Multi-Project Support

Every tool accepts an optional directory parameter to target a different project. No restarts needed.

opencode_ask({ directory: "/home/user/mobile-app", prompt: "Add navigation" })
opencode_ask({ directory: "/home/user/web-app", prompt: "Add auth" })

Environment Variables

All optional. Only needed if you've changed defaults on the OpenCode server.

| Variable | Default | Description | |---|---|---| | OPENCODE_BASE_URL | http://127.0.0.1:4096 | OpenCode server URL | | OPENCODE_SERVER_USERNAME | opencode | HTTP basic auth username | | OPENCODE_SERVER_PASSWORD | (none) | HTTP basic auth password (enables auth when set) | | OPENCODE_AUTO_SERVE | true | Auto-start opencode serve if not running | | OPENCODE_DEFAULT_PROVIDER | (none) | Default provider ID when not specified p