opencode-cli-mcp

📖 Installation Guide - quick start, manual setup, and troubleshooting 📖 Onboarding - 5-minute first-run guide 📖 Full reference - tools, endpoints, env vars, architecture

MCP server wrapping opencode CLI's HTTP API (opencode serve) into 22 FastMCP tools (7 primary portmanteaus + 15 legacy aliases). Also includes a FastAPI REST bridge (unified with the MCP endpoint on one port), 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).

🧠 Eternal Session Memory — opencode stores every session since install in one searchable SQLite database. Ask it "what were we discussing last December about X?" — no other agentic IDE can do that. opencode-cli-mcp makes that memory searchable, exportable, editable, and backed up.

What can you do?

Related MCP server: MCP Proxy Server

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 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) + unified backend (:10951, REST /api/* + MCP /mcp on one port) + Vite frontend (:10950).

MCP Server Only

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

MCP Tools

Primary surface - seven portmanteaus (operation discriminator):

15 legacy atomic tools remain mounted as aliases through 0.2.x (opencode_run_agent, opencode_get_run_status, opencode_list_runs, opencode_cancel_run, opencode_list_sessions, opencode_get_session, opencode_send_message, opencode_get_messages, opencode_session_diff, opencode_server_status, opencode_list_providers, opencode_get_project, opencode_get_config, opencode_get_health, opencode_launch_ui, plus opencode_session_grep / opencode_export_session / opencode_config_drift / opencode_mcp_pulse).

Prefab in-chat cards: show_runs_app, show_sessions_app, show_status_app.

Eternal Session Memory

opencode records every conversation and agent run since install into one searchable SQLite database (~/.local/share/opencode/opencode.db). No other agentic IDE has this — you cannot ask Claude or Cursor "what were we discussing last December about santiclaus-mcp?", but you can ask opencode:

opencode_depot(action="search", query="santiclaus")          # wayback find - full-text across ALL transcripts
opencode_depot(action="rag", query="santiclaus")             # semantic recall - embeddings over indexed transcripts
opencode_depot(action="rag_index")                           # build the RAG index (once)
opencode_sessions(action="get", session_id="ses_...")        # metadata
opencode_sessions(action="messages", session_id="ses_...")   # the transcript
opencode_sessions(action="export", session_id="ses_...")     # markdown/html document
opencode_backups(action="create", kind="all")                # protect it (autobackup 24h)

Full walkthrough: docs/ETERNAL_MEMORY.md (also on the webapp Help page and Depot page).

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

Stack

• Backend: Python 3.12+, FastMCP 3.4.4, FastAPI, uvicorn, httpx, pydantic v2, prefab-ui, psutil, SQLite (job store)

• Frontend: React 18, Vite 5, TypeScript, TailwindCSS 3.4, Zustand, Framer Motion, Lucide, React Router, @tauri-apps/api

• Native: Tauri 2 (NSIS installer, embedded PyInstaller backend)

• Quality: ruff, biome, pytest (+coverage), Playwright e2e, pre-commit, just

Ports

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)