Content
<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
```sh
npm install -g @kud/mcp-opencode
```
Requires [opencode](https://opencode.ai) installed with at least one provider configured, and Node.js ≥ 20.
## Usage
Add the server to your MCP client configuration:
```json
{
"mcpServers": {
"opencode": {
"command": "npx",
"args": ["-y", "@kud/mcp-opencode"]
}
}
}
```
To restrict which models are available, pass environment variables:
```json
{
"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
```sh
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](https://kud.io/projects/mcp-opencode/docs)**
