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

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

Resources (10)

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

Prompts (6)

Guided workflow templates your client can offer as selectable actions:

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.

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