mcp-opencode

<div align="center">

MCP server for opencode — query github-copilot models via a persistent opencode server.

<a href="https://kud.io/projects/mcp-opencode">Website</a> · <a href="https://kud.io/projects/mcp-opencode/docs">Documentation</a>

</div>

Features

• Zero API key — routes prompts through a locally running opencode server, so no provider credentials are needed in your AI client.
• Multi-model support — any model configured in opencode is available; query GPT-4.1, Claude, Gemini, or any other supported provider.
• Model filtering — restrict or block models via MCP_OPENCODE_MODEL_ALLOW and MCP_OPENCODE_MODEL_BLOCK environment variables using glob-style patterns.
• Auto-start — if opencode is not already listening on port 4096, the server spawns it automatically in the background.
• Session isolation — each query call creates and destroys a dedicated opencode session, preventing state leakage between calls.
• Works everywhere — compatible with Claude Desktop, Claude Code, Cursor, Windsurf, VSCode, and any MCP-capable client.

Install

npm install -g @kud/mcp-opencode

Requires opencode installed with at least one provider configured, and Node.js ≥ 20.

Usage

Add the server to your MCP client configuration:

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

To restrict which models are available, pass environment variables:

{
  "mcpServers": {
    "opencode": {
      "command": "npx",
      "args": ["-y", "@kud/mcp-opencode"],
      "env": {
        "MCP_OPENCODE_MODEL_ALLOW": "github-copilot/*",
        "MCP_OPENCODE_MODEL_BLOCK": "github-copilot/gpt-4o-mini"
      }
    }
  }
}

Available tools

Tool	Description
query	Send a prompt to an opencode model. Accepts prompt (required) and model (optional, default: github-copilot/gpt-4.1).
list_models	List models available through the running opencode server. Accepts an optional provider filter (e.g. anthropic).

Development

git clone https://github.com/kud/mcp-opencode.git
cd mcp-opencode
npm install
npm run build
npm test

Use the local .mcp.json to connect Claude Code to your dev build, or npm run inspect to open the MCP Inspector against the compiled output.

Script	Purpose
npm run dev	Run from source via tsx
npm run build	Compile TypeScript to dist/
npm test	Run the Vitest test suite
npm run inspect	Open MCP Inspector against the built server

📚 Full documentation → mcp-opencode/docs