███╗   ███╗ ██████╗██████╗      ██████╗ ██████╗ ███████╗███╗   ██╗ ██████╗ ██████╗ ██████╗ ███████╗
████╗ ████║██╔════╝██╔══██╗    ██╔═══██╗██╔══██╗██╔════╝████╗  ██║██╔════╝██╔═══██╗██╔══██╗██╔════╝
██╔████╔██║██║     ██████╔╝    ██║   ██║██████╔╝█████╗  ██╔██╗ ██║██║     ██║   ██║██║  ██║█████╗
██║╚██╔╝██║██║     ██╔═══╝     ██║   ██║██╔═══╝ ██╔══╝  ██║╚██╗██║██║     ██║   ██║██║  ██║██╔══╝
██║ ╚═╝ ██║╚██████╗██║         ╚██████╔╝██║     ███████╗██║ ╚████║╚██████╗╚██████╔╝██████╔╝███████╗
╚═╝     ╚═╝ ╚═════╝╚═╝          ╚═════╝ ╚═╝     ╚══════╝╚═╝  ╚═══╝ ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝

Query any opencode model from your AI assistant — no API key required.

Features • Quick Start • Installation • Tools • Development

Features

• 🤖 Query any model — send prompts to anthropic, github-copilot, google-vertex, and more
• 🔍 Discover models — list all models your opencode is configured for, optionally filtered by provider
• 🚀 Zero config auth — no API tokens; delegates authentication entirely to opencode
• ⚡ Auto-start — spins up the opencode server automatically if it isn't running
• 🛡️ Allow/block filters — restrict which models are accessible via OPENCODE_MODEL_ALLOW / OPENCODE_MODEL_BLOCK
• 🔌 Works with any opencode provider — anthropic, github-copilot, google-vertex, and any others you've configured

Quick Start

Prerequisites

• opencode installed and at least one provider configured
• Node.js ≥ 20

Install

npm install -g @kud/mcp-opencode

Minimal Claude Code config

opencode:
  transport: stdio
  command: npx
  args:
    - -y
    - "@kud/mcp-opencode"

Installation

Add to ~/.claude/claude_code_config.yml (or your profile config):

opencode:
  transport: stdio
  command: npx
  args:
    - -y
    - "@kud/mcp-opencode"

Then run:

my ai client claude-code

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Restart Claude Desktop.

Edit %APPDATA%\Claude\claude_desktop_config.json:

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

Restart Claude Desktop.

In Cursor settings → MCP → Add server:

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

Edit ~/.codeium/windsurf/mcp_config.json:

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

Edit .vscode/mcp.json in your workspace:

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

Available Tools

Querying

| Tool | Description | | ------- | ---------------------------------------------------------- | | query | Send a prompt to an opencode model and return the response |

Discovery

| Tool | Description | | ------------- | ----------------------------------------------------------- | | list_models | List all available models; pass a provider name to filter |

Total: 2 Tools

Model Filtering

Restrict which models are accessible using environment variables:

| Variable | Description | Example | | ---------------------- | ----------------------------------------------------------- | ------------------------------ | | OPENCODE_MODEL_ALLOW | Comma-separated allowlist (supports provider/* wildcards) | github-copilot/*,anthropic/* | | OPENCODE_MODEL_BLOCK | Comma-separated blocklist | anthropic/claude-opus-4-6 |

Both exact model IDs (anthropic/claude-sonnet-4-6) and provider wildcards (github-copilot/*) are supported. If OPENCODE_MODEL_ALLOW is unset, all models are allowed.

Example config with filtering:

{
  "mcpServers": {
    "opencode": {
      "command": "npx",
      "args": ["-y", "@kud/mcp-opencode"],
      "env": {
        "OPENCODE_MODEL_ALLOW": "github-copilot/*,anthropic/*",
        "OPENCODE_MODEL_BLOCK": "anthropic/claude-opus-4-6"
      }
    }
  }
}

Example Conversations

"What models do I have access to?" → Calls list_models, returns all configured models grouped by provider.

"List only my Anthropic models." → Calls list_models with provider: "anthropic".

"Ask GPT-4.1 via Copilot to explain what a monad is." → Calls query with model: "github-copilot/gpt-4.1".

"Use Claude Sonnet to review this diff and suggest improvements." → Calls query with model: "anthropic/claude-sonnet-4-6" and the diff as the prompt.

"Get a second opinion from Gemini on this architecture decision." → Calls query with model: "google-vertex/gemini-2.5-pro".

"What's the default model being used?" → github-copilot/gpt-4.1 — shown in the query tool description.

Development

Project structure

mcp-opencode/
├── src/
│   ├── index.ts              # Server entry point + all tool handlers
│   └── __tests__/
│       └── tools.test.ts     # Unit tests
├── dist/                     # Compiled output (generated)
├── package.json
├── tsconfig.json
└── vitest.config.ts

Scripts

| Script | Description | | --------------------- | --------------------------------------- | | npm run build | Compile TypeScript to dist/ | | npm run build:watch | Watch mode | | npm run dev | Run directly via tsx (no build needed) | | npm test | Run tests | | npm run test:watch | Watch mode tests | | npm run coverage | Test coverage report | | npm run inspect | Open MCP Inspector against built server | | npm run inspect:dev | Open MCP Inspector via tsx | | npm run typecheck | Type-check without emitting | | npm run clean | Remove dist/ |

Dev workflow

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 directly to your dev build:

# Already present in the repo root:
cat .mcp.json
# { "mcpServers": { "opencode": { "command": "node", "args": ["./dist/index.js"] } } }

MCP Inspector

npm run inspect

Opens the interactive inspector at http://localhost:5173 — useful for testing tools manually without a full AI client.

How it works

This MCP server acts as a bridge between your AI assistant and opencode:

1. On first use, it checks whether the opencode HTTP server is running on 127.0.0.1:4096
2. If not, it spawns opencode serve in the background and waits for it to be ready
3. Each query call creates a temporary opencode session, sends the prompt, waits for the response, then deletes the session
4. Authentication is handled entirely by opencode — configure your providers once in opencode and this MCP inherits them automatically

Troubleshooting

Server not showing in the MCP list

• Ensure opencode is installed: which opencode
• Check Node.js version: node --version (must be ≥ 20)
• Try running manually: npx @kud/mcp-opencode

"failed to create session" error

• Make sure opencode is installed and at least one provider is configured
• Run opencode models to verify your setup

"The requested model is not supported" error

• The model ID exists in opencode's registry but isn't supported by the provider's API
• Use list_models and pick a working model — e.g. github-copilot/gpt-4.1 instead of github-copilot/claude-sonnet-4

Model not in the list

• The model list reflects your opencode configuration, not the full marketplace
• Run opencode models in your terminal to see the same list

MCP Inspector logs

npm run inspect

Security best practices

• No credentials are stored in or passed through this MCP server
• All authentication is delegated to opencode's own config
• Use OPENCODE_MODEL_ALLOW to restrict access to specific providers if needed
• Never commit .mcp.json or .claude/ (both are gitignored)

Tech Stack

| | | | ----------------- | -------------------------------- | | Runtime | Node.js ≥ 20 | | Language | TypeScript 5.x (ESM) | | Protocol | Model Context Protocol (MCP) 1.0 | | opencode SDK | @opencode-ai/sdk | | Schema | Zod | | Tests | Vitest | | Module System | ESM ("type": "module") |

Contributing

1. Fork the repo
2. Create a branch: git checkout -b feat/my-change
3. Make your changes and add tests
4. Run npm run build && npm test
5. Open a pull request

License

MIT — see LICENSE.

Acknowledgments

Built on top of opencode by the SST team and the Model Context Protocol by Anthropic.

Resources

• opencode documentation
• Model Context Protocol
• @kud/mcp-opencode on npm

Support

• 🐛 Report a bug
• 💡 Request a feature

Made with ❤️ for opencode users

⭐ Star this repo if it's useful to you · ↑ Back to top