Opencode Cli

📖 Installation Guide — quick start, manual setup, and troubleshooting

MCP server wrapping opencode CLI's HTTP API (opencode serve) into 14 FastMCP tools. Also includes a FastAPI REST bridge, a Vite/React fleet-standard dashboard, and OpenCode custom tools that extend opencode itself.

Pattern: Plan with Claude, implement with opencode. Claude (expensive, high-judgment) orchestrates and supervises; opencode handles implementation grunt work on cheaper models (DeepSeek V4 Flash/Pro).

Quick Start

git clone https://github.com/sandraschi/opencode-cli-mcp
cd opencode-cli-mcp
just

This opens an interactive dashboard showing all available commands. Run just bootstrap to install dependencies, then just serve or just dev to start.

Manual Setup

If you don't have just installed:

Prerequisites

• opencode CLI: npm i -g opencode-ai
• Python 3.12+
• Node.js 18+

Run Everything

.\start.ps1 Starts: opencode serve (:4096) + FastAPI backend (:10951) + Vite frontend (:10950).

MCP Server Only

uv run -m opencode_cli_mcp.server Configure in Claude Desktop / Cursor / Windsurf (see Integration Guide).

14 MCP Tools

Tool	Purpose
opencode_run_agent	Launch agent (background or blocking)
opencode_get_run_status	Poll running agent
opencode_list_runs	List all agent runs
opencode_cancel_run	Cancel a stuck run
opencode_list_sessions	List opencode sessions
opencode_get_session	Session details
opencode_session_diff	Files changed in a session
opencode_session_files	Files touched in a session
opencode_export_session	Export session as JSON
opencode_send_message	Continue a session
opencode_get_messages	Session transcript
opencode_server_status	Server health + config
opencode_list_providers	Configured LLM providers
opencode_get_project	Active project context

Key Workflows

See Usage Guide for full details.

Basic: Launch -> Poll -> Review

opencode_run_agent(prompt="refactor main.py", wait=false)
    -> { job_id: "abc" }
opencode_get_run_status("abc")     -> poll until completed
opencode_session_diff("session-xyz") -> review changes

Multi-Agent Sweep

Launch N agents across N repos in parallel, poll all, review diffs. Designed for fleet-wide operations.

Interactive Supervision

Start an agent, read its messages mid-task, send corrections, review final diff.

OpenCode Custom Tools

Copy .opencode/tools/*.ts into your opencode project to give opencode's LLM direct access to MCP fleet management, session inspection, and system diagnostics. 6 tools covering fleet, sessions, runs, system, providers, and tool discovery. See the OC Tools page in the webapp for full documentation and source.

Documentation

Doc	Description
Usage Guide	All tools, workflows, async patterns, webapp pages
Integration Guide	MCP client config (Claude Desktop, Cursor, Windsurf)
Advanced Usage	Async patterns, session management, cross-project, custom tools
Improvement Plan	Known issues and roadmap
Assessment	Architecture review and bug audit
Changelog	Version history

Ports

Port	Service
10950	Frontend (Vite)
10951	Backend (FastAPI)
4096	opencode serve

Security

This MCP server runs arbitrary shell commands (opencode run) from LLM prompts. Only install in environments where you trust your MCP client (Claude Desktop, Cursor) and the models it uses.

Fleet

• Registered in mcp-central-docs: ports 10950/10951
• fleet-registry.json and glama.json in repo root
• Webapp dashboard: http://localhost:10950 (run .\start.ps1)