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