An MCP server that gives any MCP-compatible client full access to OpenCode. Manage sessions, send prompts, search files, review diffs, configure providers, control the TUI, and more.
71 tools | 10 resources | 5 prompts | Multi-project support | Auto-start
Add to your MCP client and go. The server automatically detects and starts the OpenCode server if it's not already running — no manual opencode serve step needed.
Prerequisite: OpenCode must be installed on your system. Install:
curl -fsSL https://opencode.ai/install | bashornpm i -g opencode-aiorbrew install sst/tap/opencode
Pick your client below. No authentication is needed by default — just add the config and restart your client.
Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"opencode": {
"command": "npx",
"args": ["-y", "opencode-mcp"]
}
}
}Claude Code:
claude mcp add opencode -- npx -y opencode-mcpCursor (.cursor/mcp.json):
{
"mcpServers": {
"opencode": {
"command": "npx",
"args": ["-y", "opencode-mcp"]
}
}
}Windsurf (~/.windsurf/mcp.json):
{
"mcpServers": {
"opencode": {
"command": "npx",
"args": ["-y", "opencode-mcp"]
}
}
}VS Code — GitHub Copilot (settings.json):
{
"github.copilot.chat.mcp.servers": [
{
"name": "opencode",
"type": "stdio",
"command": "npx",
"args": ["-y", "opencode-mcp"]
}
]
}Cline (VS Code extension settings):
{
"mcpServers": {
"opencode": {
"command": "npx",
"args": ["-y", "opencode-mcp"]
}
}
}Continue (.continue/config.json):
{
"mcpServers": {
"opencode": {
"command": "npx",
"args": ["-y", "opencode-mcp"]
}
}
}Zed (settings.json):
{
"context_servers": {
"opencode": {
"command": {
"path": "npx",
"args": ["-y", "opencode-mcp"]
}
}
}
}Amazon Q (VS Code settings.json):
{
"amazon-q.mcp.servers": [
{
"name": "opencode",
"type": "stdio",
"command": "npx",
"args": ["-y", "opencode-mcp"]
}
]
}That's it. Your MCP client now has access to the entire OpenCode API. The MCP server will auto-start opencode serve if it's not already running.
By default, the MCP server connects to http://127.0.0.1:4096 with no authentication. Both username and password are optional — auth is only needed if you've enabled it on the OpenCode server side.
If the OpenCode server is on a different host/port or has auth enabled, pass environment variables:
{
"mcpServers": {
"opencode": {
"command": "npx",
"args": ["-y", "opencode-mcp"],
"env": {
"OPENCODE_BASE_URL": "http://192.168.1.10:4096",
"OPENCODE_SERVER_USERNAME": "myuser",
"OPENCODE_SERVER_PASSWORD": "mypass"
}
}
}
}To disable auto-start (if you prefer to manage the OpenCode server yourself):
{
"env": {
"OPENCODE_AUTO_SERVE": "false"
}
}High-level tools designed to be the easiest way for an LLM to interact with OpenCode:
| Tool | What it does |
|---|---|
opencode_setup |
Check server health, provider config, and project status — use as first step |
opencode_ask |
Create session + send prompt + get answer in one call |
opencode_reply |
Follow-up message in an existing session |
opencode_conversation |
Formatted conversation history |
opencode_sessions_overview |
Quick overview of all sessions |
opencode_context |
Project + path + VCS + config + agents in one call |
opencode_wait |
Poll an async session until it finishes |
opencode_review_changes |
Formatted diff summary for a session |
Create, list, get, delete, update, fork, share, abort, revert sessions. Get diffs, todos, summaries, child sessions, and respond to permission requests.
Send prompts (sync or async), list/get messages, execute slash commands, run shell commands.
Search text/regex across the project, find files by name, find workspace symbols, list directories, read files, check VCS file status.
Get/update config, list providers and models, manage auth (API keys, OAuth).
Remote-control the OpenCode TUI: append/submit/clear prompts, execute commands, show toasts, open dialogs (help, sessions, models, themes).
Health checks, VCS info, LSP/formatter status, MCP server management, agent/command listing, logging, SSE event polling.
Browseable data endpoints:
| URI | Description |
|---|---|
opencode://project/current |
Current active project |
opencode://config |
Current configuration |
opencode://providers |
Providers with models |
opencode://agents |
Available agents |
opencode://commands |
Available commands |
opencode://health |
Server health and version |
opencode://vcs |
Version control info |
opencode://sessions |
All sessions |
opencode://mcp-servers |
MCP server status |
opencode://file-status |
VCS file status |
Guided workflow templates:
| Prompt | Description |
|---|---|
opencode-code-review |
Structured code review from session diffs |
opencode-debug |
Guided debugging workflow |
opencode-project-setup |
Get oriented in a new project |
opencode-implement |
Have OpenCode implement a feature |
opencode-session-summary |
Summarize a session |
All environment variables are optional. You only need to set them if you've changed the defaults on the OpenCode server side.
| Variable | Description | Default | Required |
|---|---|---|---|
OPENCODE_BASE_URL |
URL of the OpenCode server | http://127.0.0.1:4096 |
No |
OPENCODE_SERVER_USERNAME |
HTTP basic auth username | opencode |
No |
OPENCODE_SERVER_PASSWORD |
HTTP basic auth password | (none — auth disabled) | No |
OPENCODE_AUTO_SERVE |
Auto-start opencode serve if not running |
true |
No |
Note: Authentication is disabled by default. It only activates when
OPENCODE_SERVER_PASSWORDis set on both the OpenCode server and the MCP server.
MCP Client <--stdio--> opencode-mcp <--HTTP--> OpenCode Server
(Claude, Cursor, etc.) (this package) (opencode serve)
The MCP server communicates over stdio using the Model Context Protocol. When a client invokes a tool, the server translates it into HTTP calls against the OpenCode headless API.
Auto-start flow: On startup, the MCP server checks if the OpenCode server is already running (via the /global/health endpoint). If not, it finds the opencode binary on your system and spawns opencode serve as a child process. The child is automatically cleaned up when the MCP server exits.
Every tool accepts an optional directory parameter that targets a specific project directory. This lets you work on multiple projects from a single OpenCode server without restarting anything.
# First-time setup: check server status and configure providers
opencode_setup()
# Set an API key (one-time, global — shared across all projects)
opencode_auth_set({ providerId: "anthropic", type: "api", key: "sk-ant-..." })
# Work on a mobile app
opencode_ask({
directory: "/home/user/projects/mobile-app",
prompt: "Set up navigation with React Navigation"
})
# Switch to a web app — same server, different directory
opencode_ask({
directory: "/home/user/projects/web-app",
prompt: "Add authentication to the Next.js app"
})
# Go back to the mobile app — no restart needed
opencode_reply({
directory: "/home/user/projects/mobile-app",
sessionId: "sess_abc123",
prompt: "Now add a login screen"
})
When directory is omitted, the OpenCode server uses its own working directory (where opencode serve was started).
How it works internally: The directory parameter is sent as the x-opencode-directory HTTP header. The OpenCode server lazily initializes a separate instance per directory (with its own LSP, VCS, MCP servers, sessions, etc.) and caches them in memory.
src/
index.ts Entry point — wires everything together
server-manager.ts Auto-detect, find, and start OpenCode server
client.ts HTTP client with retry, SSE, error categorization
helpers.ts Smart response formatting for LLM-friendly output
resources.ts MCP Resources (10 browseable data endpoints)
prompts.ts MCP Prompts (5 guided workflow templates)
tools/
workflow.ts High-level workflow tools (8)
session.ts Session management tools (18)
message.ts Message/prompt tools (6)
file.ts File and search tools (6)
tui.ts TUI remote control tools (9)
config.ts Config tools (3)
provider.ts Provider/auth tools (5)
misc.ts System, agents, LSP, MCP, logging tools (13)
events.ts SSE event polling (1)
global.ts Health check (1)
project.ts Project tools (2)
git clone https://github.com/AlaeddineMessadi/opencode-mcp.git
cd opencode-mcp
npm install
npm run build # compiles TypeScript and sets executable permissions
npm start # runs the MCP server
npm run dev # watch mode- Getting Started — step-by-step setup guide
- Configuration — all env vars and MCP client configs
- Tools Reference — detailed reference for all 71 tools
- Resources Reference — all 10 MCP resources
- Prompts Reference — all 5 MCP prompts
- Usage Examples — real workflow examples
- Architecture — system design and data flow
Works with any MCP-compatible client, including: