This MCP server acts as a bridge between your MCP clients (such as Claude Desktop, Claude Code, Cursor, Windsurf, VS Code Copilot, and other MCP-compatible tools) and OpenCode's headless API. It auto-starts the OpenCode service when needed and exposes the 79 OpenCode tools (grouped into workflow, session, file/search, system, and more) so your AI agents can delegate coding tasks—writing, testing, refactoring, and running commands—directly within your project. To begin, install and run the MCP server, then configure your MCP clients to point at this server (for example using an opencode entry with command npx -y opencode-mcp). Once configured, your clients can invoke tools like opencode_setup, opencode_run, opencode_ask, and opencode_fire to create sessions, run tasks, check progress, and fetch results, all through the standard MCP workflow.

Typical usage involves adding the opencode-mcp server to your client configs, restarting your MCP client, and then issuing prompts or workflows such as building features, running tests, or performing code reviews. You can also leverage multi-project support by providing a directory parameter in your tool calls, enabling parallel work across multiple repositories without restarts. The server translates MCP tool calls into HTTP requests to the OpenCode headless API and, if needed, automatically starts the OpenCode server.

Key workflow tools include: opencode_setup (health and project status), opencode_ask (start a session and get an answer in one go), opencode_run (execute a task and wait for completion), and opencode_wait (poll until a running session finishes). These, along with the other 79 tools, enable a wide range of automated coding tasks, from repairing bugs to scaffolding features and generating tests.

Prerequisites

• Node.js (recommended LTS) installed on your machine
• Access to a running or locally installable OpenCode server per the OpenCode docs
• Git (optional, for cloning the repository)

Install and run

1. Clone or install the MCP package: git clone https://github.com/AlaeddineMessadi/opencode-mcp.git cd opencode-mcp

2. Install dependencies: npm install

3. Build the MCP server (if your project requires building): npm run build

4. Start the MCP server: npm start # run the MCP server

   or for development/watch mode:

   npm run dev

5. Ensure OpenCode server is accessible. If you run OpenCode locally, start it or verify the base URL in OPENCODE_BASE_URL.

6. Configure a client (example for Claude Code / other MCP clients):

   • Add the opencode MCP server to your client config, e.g.: { "mcpServers": { "opencode": { "command": "npx", "args": ["-y", "opencode-mcp"] } } }

7. Restart your MCP client and verify tools are available from the OpenCode suite.

Environment variables are optional and override defaults for connecting to the OpenCode server. Key variables include OPENCODE_BASE_URL (default http://127.0.0.1:4096) and OPENCODE_AUTO_SERVE (default true to auto-start opencode serve when needed). If you enable authentication, set OPENCODE_SERVER_USERNAME and OPENCODE_SERVER_PASSWORD. You can also set OPENCODE_DEFAULT_PROVIDER and OPENCODE_DEFAULT_MODEL to tailor tool defaults per session. If you encounter connectivity issues, verify that the opencode headless API is reachable from the MCP server host and that firewall rules permit HTTP requests to the OpenCode server. When upgrading, re-check compatibility notes in the docs, as tool availability and endpoints may evolve alongside the 79 tools in the suite.