OpenCode MCP Tool

Documentation available in docs/ – Examples, FAQ, troubleshooting, best practices

This is a Model Context Protocol (MCP) server that allows AI assistants to interact with the OpenCode CLI. It enables AI assistants to leverage multiple AI models through a unified interface, with features like plan mode for structured thinking and extensive model selection.

• Ask questions through multiple AI models via Claude or other MCP clients
• Use plan mode for structured analysis and safer operations

TLDR

Use OpenCode’s multi-model capabilities directly in Claude Code with flexible model selection and plan mode features.

Prerequisites

Before using this tool, ensure you have:

1. Node.js (v16.0.0 or higher)
2. OpenCode CLI installed and configured

One-Line Setup (Claude Code)

claude mcp add opencode -- npx -y @gilby125/opencode-mcp-tool -- --model google/gemini-2.5-pro

Codex CLI Setup

If you’re using the OpenAI Codex CLI as your MCP client, add this server with:

codex mcp add opencode -- npx -y @gilby125/opencode-mcp-tool -- --model google/gemini-2.5-pro --fallback-model google/gemini-2.5-flash

After that, start Codex CLI as usual and you can talk to OpenCode via natural language (for example, “use opencode to explain index.html”) and let Codex call the MCP tools when helpful.

Verify Installation

Type /mcp inside Claude Code to verify the opencode-cli MCP is active.

---

Alternative: Import from Claude Desktop

If you already have it configured in Claude Desktop:

1. Add to your Claude Desktop config:

"opencode": {
  "command": "npx",
  "args": ["-y", "@gilby125/opencode-mcp-tool", "--", "--model", "google/gemini-2.5-pro"]
}

2. Import to Claude Code:

claude mcp add-from-claude-desktop

Configuration

Register the MCP server with your MCP client. Note: The server requires a primary model to be specified.

For NPX Usage (Recommended)

Add this configuration to your Claude Desktop config file:

{
  "mcpServers": {
    "opencode": {
      "command": "npx",
      "args": ["-y", "@gilby125/opencode-mcp-tool", "--", "--model", "google/gemini-2.5-pro", "--fallback-model", "google/gemini-2.5-flash"]
    }
  }
}

For Global Installation

If you installed globally, use this configuration instead:

{
  "mcpServers": {
    "opencode": {
      "command": "opencode-mcp",
      "args": ["--model", "google/gemini-2.5-pro", "--fallback-model", "google/gemini-2.5-flash"]
    }
  }
}

Codex CLI Configuration

To use this server with the OpenAI Codex CLI, add the following to your ~/.codex/config.toml:

[mcp_servers.opencode]
command = "opencode-mcp"
args = ["--model", "google/gemini-2.5-pro", "--fallback-model", "google/gemini-2.5-flash"]
startup_timeout_sec = 20
tool_timeout_sec = 300