How do I use opencode-cli-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@opencode-cli-mcp run agent to analyze the current project" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

opencode-cli-mcp

MCP server that wraps opencode CLI's HTTP API (opencode serve) into MCP tools, plus a SOTA fleet-standard webapp dashboard.

Quick Start

.\start.ps1                  # OpenCode serve + API + frontend
uv run -m opencode_cli_mcp.server    # MCP server only (stdio)

Requires: opencode CLI (npm i -g opencode-ai), Python 3.12+, Node.js 18+.

MCP Tools (14 atomic)

Tool	Purpose
`opencode_run_agent`	Launch agent (background or blocking)
`opencode_get_run_status`	Poll running agent for progress
`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`	What 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 running session
`opencode_get_messages`	Session transcript
`opencode_server_status`	Server health + config
`opencode_list_providers`	Configured LLM providers
`opencode_get_project`	Active project context

Async Workflow (recommended)

opencode_run_agent(prompt="refactor main.py", wait=false)
    → { job_id: "abc123" }

opencode_get_run_status("abc123")       # poll until completed
    → { status: "completed", stdout: "...", exit_code: 0 }

opencode_session_diff("session-xyz")     # review changes
    → { diff: { created: [...], modified: [...], deleted: [...] } }

Architecture

MCP hosts  →  opencode-cli-mcp (FastMCP 3.2, stdio)
                   ↕ httpx
              opencode serve (HTTP :4096)

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 and use in environments where you trust your MCP client (Claude Desktop, Cursor, etc.) and the models it uses.