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
- 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/sdkif one isn't already running. No manual steps.
Prerequisite: OpenCode must be installed.
curl -fsSL https://opencode.ai/install | bashornpm i -g opencode-aiorbrew install sst/tap/opencode
Claude Code:
claude mcp add opencode -- npx -y opencode-mcpClaude 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.
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.
The 80 tools are organized into tiers. Start with the workflow tools — they handle the common patterns in a single call.
| 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 |
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
| 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 |
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 |
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 |
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" })
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) |
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 testsEnd-to-end test against a running OpenCode server:
npm run build && node scripts/mcp-smoke-test.mjs- 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