OpenCode MCP Tool

OpenCode MCP Tool is a Model Context Protocol (MCP) server that lets you talk to the OpenCode CLI through multiple AI models from a single, unified interface. It supports selecting models, planning mode for structured thinking, and safe execution of operations, making it easier to experiment with different models and workflows from your MCP client.

How to use

You interact with the OpenCode MCP server from any MCP client by selecting a server name (opencode) and issuing your analysis or coding requests. You can use it in plan mode for structured analysis, or in immediate mode for direct execution. Start by choosing your preferred client (for example Claude Code, Claude Desktop, or OpenAI Codex CLI) and connect to the opencode MCP server using the provided commands. When you want to explain code, analyze a project, or run safe scripted operations, frame your prompt to include file references with the @ syntax for precise context.

How to install

Prerequisites you need before installing and using the OpenCode MCP Tool server are straightforward.

1. Install Node.js (version 16.0.0 or higher). 2) Install or configure the OpenCode CLI as required by your workflow.

Then follow these concrete commands to set up the MCP server with your client.

One-Line Setup (Claude Code) to add the opencode MCP server via NPX:

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

Codex CLI Setup for the opencode MCP server (includes a fallback model):

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

After adding, start using the MCP server by issuing a verification command in your client. For Claude Code, type a command that invokes the MCP server, for example: /mcp to verify the opencode MCP is active.

Alternative setup for Claude Desktop users who prefer a JSON config, place this in your Claude Desktop config and then import the config into Claude Code as needed.

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

Configuration and usage notes

You can connect to the opencode MCP server using either a local NPX-based command or a globally installed runtime. The following configurations show the exact command invocations you should use. If you install globally, provide the model and fallback model to enable graceful fallback.

NPX usage (preferred for quick start):

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

Global installation (if you install opencode-mcp globally):

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

Available tools

ask-opencode

Execute OpenCode with model selection and mode control. Use the specified model and mode to analyze prompts, include file references with @ syntax, or perform general searches.

brainstorm

Generate novel ideas using frameworks like SCAMPER or design-thinking, with optional domain context and feasibility analysis.

timeout-test

Test timeout prevention by running a timed operation for a specified duration to ensure safe handling.

ping

Echo test tool that returns a message, confirming the server is reachable.

Help

Shows the OpenCode CLI help text to guide usage and available commands.