opencode-mcp

An MCP server that gives any MCP-compatible client full access to a running OpenCode instance. Manage sessions, send prompts, search files, review diffs, configure providers, control the TUI, and more.

70 tools | 10 resources | 5 prompts

Quick Start

1. Start an OpenCode server

opencode serve

2. Add to your MCP client

Pick your client below. No authentication is needed by default — just add the config and restart your client.

Claude Desktop (claude_desktop_config.json):

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

Claude Code:

claude mcp add opencode -- npx -y opencode-mcp

Cursor (.cursor/mcp.json):

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

Windsurf (~/.windsurf/mcp.json):

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

VS Code — GitHub Copilot (settings.json):

{
  "github.copilot.chat.mcp.servers": [
    {
      "name": "opencode",
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "opencode-mcp"]
    }
  ]
}

Cline (VS Code extension settings):

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

Continue (.continue/config.json):

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

Zed (settings.json):

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

Amazon Q (VS Code settings.json):

{
  "amazon-q.mcp.servers": [
    {
      "name": "opencode",
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "opencode-mcp"]
    }
  ]
}

That's it. Your MCP client now has access to the entire OpenCode API.

Custom server URL or authentication (optional)

By default, the MCP server connects to http://127.0.0.1:4096 with no authentication. Both username and password are optional — auth is only needed if you've enabled it on the OpenCode server side.

If the OpenCode server is on a different host/port or has auth enabled, pass environment variables:

{
  "mcpServers": {
    "opencode": {
      "command": "npx",
      "args": ["-y", "opencode-mcp"],
      "env": {
        "OPENCODE_BASE_URL": "http://192.168.1.10:4096",
        "OPENCODE_SERVER_USERNAME": "myuser",
        "OPENCODE_SERVER_PASSWORD": "mypass"
      }
    }
  }
}

What Can It Do?

Workflow Tools (start here)

High-level tools designed to be the easiest way for an LLM to interact with OpenCode:

Session Tools (18)

Create, list, get, delete, update, fork, share, abort, revert sessions. Get diffs, todos, summaries, child sessions, and respond to permission requests.

Message Tools (6)

Send prompts (sync or async), list/get messages, execute slash commands, run shell commands.

File & Search Tools (6)

Search text/regex across the project, find files by name, find workspace symbols, list directories, read files, check VCS file status.

Config & Provider Tools (8)

Get/update config, list providers and models, manage auth (API keys, OAuth).

TUI Control Tools (9)

Remote-control the OpenCode TUI: append/submit/clear prompts, execute commands, show toasts, open dialogs (help, sessions, models, themes).

System & Monitoring Tools (13)

Health checks, VCS info, LSP/formatter status, MCP server management, agent/command listing, logging, SSE event polling.

Resources (10)

Browseable data endpoints:

Prompts (5)

Guided workflow templates:

Environment Variables

All environment variables are optional. You only need to set them if you've changed the defaults on the OpenCode server side.

Note: Authentication is disabled by default. It only activates when OPENCODE_SERVER_PASSWORD is set on both the OpenCode server and the MCP server.

How It Works

MCP Client  <--stdio-->  opencode-mcp  <--HTTP-->  OpenCode Server
(Claude, Cursor, etc.)   (this package)            (opencode serve)

The MCP server communicates over stdio using the Model Context Protocol. When a client invokes a tool, the server translates it into HTTP calls against the OpenCode headless API. The OpenCode server must be running separately (opencode serve).

Architecture

src/
  index.ts              Entry point — wires everything together
  client.ts             HTTP client with retry, SSE, error categorization
  helpers.ts            Smart response formatting for LLM-friendly output
  resources.ts          MCP Resources (10 browseable data endpoints)
  prompts.ts            MCP Prompts (5 guided workflow templates)
  tools/
    workflow.ts         High-level workflow tools (7)
    session.ts          Session management tools (18)
    message.ts          Message/prompt tools (6)
    file.ts             File and search tools (6)
    tui.ts              TUI remote control tools (9)
    config.ts           Config tools (3)
    provider.ts         Provider/auth tools (5)
    misc.ts             System, agents, LSP, MCP, logging tools (13)
    events.ts           SSE event polling (1)
    global.ts           Health check (1)
    project.ts          Project tools (2)

Development

git clone https://github.com/AlaeddineMessadi/opencode-mcp.git
cd opencode-mcp
npm install
npm run build    # compiles TypeScript and sets executable permissions
npm start        # runs the MCP server
npm run dev      # watch mode

Documentation

• Getting Started — step-by-step setup guide
• Configuration — all env vars and MCP client configs
• Tools Reference — detailed reference for all 70 tools
• Resources Reference — all 10 MCP resources
• Prompts Reference — all 5 MCP prompts
• Usage Examples — real workflow examples
• Architecture — system design and data flow

Compatible MCP Clients

Works with any MCP-compatible client, including:

• Claude Desktop
• Claude Code
• Cursor
• Windsurf
• VS Code (GitHub Copilot)
• Cline
• Continue
• Zed
• Amazon Q

References

• OpenCode Documentation
• OpenCode Server API
• OpenCode SDK
• Model Context Protocol

License

MIT