opencode-mcp

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.

80 tools | 10 resources | 6 prompts | Multi-project | Auto-start

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 the OpenCode HTTP server in-process via the official @opencode-ai/sdk if one isn't already running. No manual steps.

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 opencode-mcp

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

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

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

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)            (in-process via @opencode-ai/sdk,
                                                    or external opencode serve)

Your MCP client calls tools over stdio. This server translates them into HTTP requests to the OpenCode headless API. If no OpenCode server is reachable at OPENCODE_BASE_URL, one is started in-process via the official @opencode-ai/sdk. The directory parameter on every tool routes that request to a specific project via the x-opencode-directory header, so a single MCP instance can fan out across many project roots.

Key Tools

The 80 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 | 3 | List, inspect, and initialize 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" })

Use opencode_project_init to scaffold a new project directory (or open a preexisting one) before the first call, so the OpenCode server registers it as a project:

opencode_project_init({ path: "/home/user/new-project" })
// → "Successfully initialized project directory at: /home/user/new-project"

opencode_run({ directory: "/home/user/new-project", prompt: "Set up a Vite + React app" })

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 an in-process OpenCode server (via @opencode-ai/sdk) if none is reachable at OPENCODE_BASE_URL | | OPENCODE_DEFAULT_PROVIDER | (none) | Default provider ID when not specified per-tool (e.g. anthropic) | | OPENCODE_DEFAULT_MODEL | (none) | Default model ID when not specified per-tool (e.g. claude-sonnet-4-5) |

Development

git clone https://github.com/AlaeddineMessadi/opencode-mcp.git
cd opencode-mcp
npm install
npm run build
npm start        # run the MCP server
npm run dev      # watch mode
npm test         # 328 tests

Smoke Testing

End-to-end test against a running OpenCode server:

npm run build && node scripts/mcp-smoke-test.mjs

Documentation

• Getting Started — step-by-step setup
• Configuration — env vars and all client configs
• Tools Reference — all 80 tools in detail
• Resources — 10 MCP resources
• Prompts — 6 guided workflow templates
• Examples — real workflow examples
• Architecture — system design and data flow

References

• OpenCode | OpenCode Docs | OpenCode Server API
• Model Context Protocol

License

MIT