mcp-opencode
๐ฎ Query any model configured in opencode from Claude โ zero API keys, auto-starts the server
Install / Use
claude mcp add kud -- npx -y github:kud/mcp-opencodeIf the server publishes to npm under a different name, use that package instead โ check the repo README.
MCP Server
Model Context Protocol server
Quality Score
Category
Development & EngineeringSupported Platforms
Tags
Our assessment of mcp-opencode
mcp-opencode scores 80/100 on our quality scale, 3563rd of 4,706 Development & Engineering skills we index.
Its MCP Server is 19 KB long, well organised into 9 sections with 6 code examples: a thorough specification that gives an agent plenty to work with.
It has 3 GitHub stars, so there is little community track record yet; judge it on its content.
Maintenance, license and trust
- The repository was last updated 4 days ago, so mcp-opencode is actively maintained.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 87/100, with 2 cautions from licensing, adoption, age or documentation. These come from repository metadata, not a code audit โ read the skill file before letting an agent act on it.
mcp-opencode compared with similar skills
All 4 of these similar skills score higher than mcp-opencode; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| mcp-opencode (this skill)by kud | 80 | 3 | 4d ago | MCP Server |
| taste-skillby Leonxlnx | 100 | 117.6k | 9d ago | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 112.7k | 10d ago | CLAUDE.md |
| rufloby ruvnet | 100 | 82.0k | today | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 79.9k | today | CLAUDE.md |
Frequently asked questions
- How do I install mcp-opencode?
- Run
claude mcp add kud -- npx -y github:kud/mcp-opencode. The install tabs above show the steps for each supported agent. - Which AI agents does mcp-opencode work with?
- It is written for Claude Code and Claude Desktop, as a MCP Server file. Other agents that read the same format can often use it too.
- Is mcp-opencode safe to use?
- It is MIT-licensed and scores 87/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is mcp-opencode still maintained?
- The repository was last updated 4 days ago, so mcp-opencode is actively maintained.
Skill content
View source on GitHub
MCP server for opencode โ query github-copilot models via a persistent opencode server.
<a href="https://kud.io/projects/mcp-opencode">Website</a> ยท <a href="https://kud.io/projects/mcp-opencode/docs">Documentation</a>
</div>Features
- Zero API key โ routes prompts through a locally running opencode server, so no provider credentials are needed in your AI client.
- Multi-model support โ any model configured in opencode is available; query GPT-4.1, Claude, Gemini, or any other supported provider.
- Model filtering โ restrict or block models via
MCP_OPENCODE_MODEL_ALLOWandMCP_OPENCODE_MODEL_BLOCKenvironment variables using glob-style patterns. - Talk to a live session โ
list_sessions,sendandreadlet your assistant hold a conversation with a running opencode session, such as the one open in your TUI, and the exchange shows up there live. - Headless jobs โ
start_instance,task,wait,list_instancesandstop_instancerun work on a private opencode server per job, with guard rails (no git push, no credentials, no permission prompts) and a ready-madeopencode --servercommand to watch it live. - Auto-start โ if opencode's background service is not running,
queryandlist_modelsstart it the same way the TUI does. - Session isolation โ each
querycall creates and destroys its own opencode session, so one-off questions leave nothing behind. - Works everywhere โ compatible with Claude Desktop, Claude Code, Cursor, Windsurf, VSCode, and any MCP-capable client.
Install
npm install -g @kud/mcp-opencode
Requires opencode 2.x (npm i -g @opencode/cli) with at least one provider configured, and Node.js โฅ 20. For opencode 1.x, stay on @kud/mcp-opencode@1.
Usage
Add the server to your MCP client configuration:
{
"mcpServers": {
"opencode": {
"command": "npx",
"args": ["-y", "@kud/mcp-opencode"]
}
}
}
To restrict which models are available, pass environment variables:
{
"mcpServers": {
"opencode": {
"command": "npx",
"args": ["-y", "@kud/mcp-opencode"],
"env": {
"MCP_OPENCODE_MODEL_ALLOW": "github-copilot/*",
"MCP_OPENCODE_MODEL_BLOCK": "github-copilot/gpt-4o-mini"
}
}
}
}
Talking to a live opencode session
opencode 2 runs one background service that every TUI window shares, and records where it listens (and its password) in its state directory. The MCP reads that registration, so any window you open with a plain opencode is reachable: no ports, no wrapper.
1. Open opencode and say something. opencode only creates a session once you send the first message.
2. Ask your assistant to talk to it. For example: "list my opencode sessions and ask the one in my-project what it thinks of this plan". It calls list_sessions to find the session, send to talk to it, and read to catch up on its history. Messages appear live in the window, and you can reply there yourself.
A window started with opencode --standalone runs a private server with a throwaway password, so the MCP cannot reach it. To use a server of your own instead of the background service, set MCP_OPENCODE_URL (and MCP_OPENCODE_PASSWORD if it has one); a TUI joins that server with opencode --server <url>.
Running headless jobs
For work you want done in the background rather than in a window you are watching, ask your assistant to start an instance and hand it a task. For example: "start an opencode instance in ~/Projects/my-app, have it add a health-check endpoint, and tell me what changed". It calls:
start_instance({ directory })โ{ port, url }: a privateopencode serveon a free port behind a generated password, separate from the background service your windows use.task({ port, prompt })โ{ session_id, port, attach }: returns at once while the job runs.wait({ port, session_id })โ status, the last assistant text and the files changed. Call it again if it comes backbusy.stop_instance({ port })when done. Idle instances are reaped afterMCP_OPENCODE_INSTANCE_TTL, and the MCP stops its own instances when it exits.
Guard rails. Nobody is there to answer a permission prompt, so a task's session never gets one: reading, editing and shell commands are allowed, while git push, git remote, gh, npm publish, git reset --hard, web fetches and searches, questions and anything outside the directory are denied. Every deny is set twice: as an opencode permission rule (session and server config) and as a policy, which opencode applies after all rules, so a repository's own opencode config cannot allow it back. The server itself runs with no git credentials (GIT_TERMINAL_PROMPT=0, GIT_SSH_COMMAND=false, an empty credential.helper), without GH_TOKEN/GITHUB_TOKEN, and with its model pinned to MCP_OPENCODE_MODEL.
Sandboxing (opt-in OS sandbox). Set MCP_OPENCODE_SANDBOX=srt to wrap each instance's opencode serve in srt (npm i -g @anthropic-ai/sandbox-runtime), enforced by the OS (macOS sandbox-exec, Linux bubblewrap) rather than by opencode's own permissions. Off by default; when the variable is unset everything behaves exactly as before. Any other non-empty value is refused with an error listing the supported values, and if srt is not on PATH the instance fails to start rather than running unsandboxed.
The server generates an srt settings file per instance (kept in a temp dir under the state dir, removed on stop_instance) and passes it as srt --settings <file> opencode serve โฆ โ always explicit, so a stray ~/.srt-settings.json can never decide the policy. The generated file allows writes only to the instance directory (realpath), its git dir(s) (both --git-common-dir and --git-dir, so worktrees work), opencode's own data/config/cache/state dirs (XDG-aware, so provider auth keeps working) and the temp dir; denies reads of credential paths (~/.ssh, ~/.aws, ~/.config/gh, ~/.gnupg, ~/.netrc, ~/.npmrc, **/.env, **/.env.*, ~/Library/Keychains, ~/.config/gcloud, ~/.kube, ~/.docker/config.json, and the background service's service.json files, which hold its password); and allows only these network destinations plus local binding for the server's own port: opencode.ai, *.opencode.ai, models.dev, api.githubcopilot.com, openrouter.ai, github.com, *.github.com, api.github.com, registry.npmjs.org, localhost, 127.0.0.1.
Sandboxed instances also get extra shell denies merged into their opencode permission config (session ruleset and OPENCODE_CONFIG_CONTENT alike): rm -rf*, sudo *, curl *|* and wget *|*. These are deny, never ask โ a headless session cannot answer and would hang โ and they are heuristic glob matches, a second layer behind the OS sandbox, not a guarantee. The opencode.ai / *.opencode.ai / api.githubcopilot.com entries were verified against the opencode 2.1.2 binary's strings (Zen API, model registry at models.opencode.ai, Copilot provider), and openrouter.ai serves the openrouter/* models; models.dev, the 1.x registry, is kept for older lookups; the rest are assumed useful for public clones and npm installs. Non-existent allowWrite entries are dropped when the file is written, so a missing opencode dir cannot break the wrap on any platform.
This is defence in depth, not a guarantee: it raises the cost of escape and of credential or network misuse, but a determined agent inside the sandbox still has the instance directory, git, and whatever the allowlist permits. Combine it with the guard rails above and review what jobs do.
Model fallback. A job tries [its model, ...MCP_OPENCODE_MODEL_FALLBACK] once each, in order. When the session stays in retry for MCP_OPENCODE_RETRY_TIMEOUT_SECONDS (default 90) or its run ends in a provider error (a provider.* error type, or model not found), the watchdog interrupts it, switches the session's model and re-prompts the same session on the next model, so history and worktree edits carry over. When the list is exhausted the job settles as error. wait and list_instances report the current model and the fallbacks taken ({ from, to, reason, at }), and wait reports retry as its own status.
Watching or stepping in. Paste the attach command from task into a terminal. It opens the session in the TUI against the instance, with the instance's password:
OPENCODE_PASSWORD=โฆ opencode --server http://127.0.0.1:53817 --session ses_โฆ
Instance registry
Instances are recorded in ~/.local/state/mcp-opencode/instances.json (or $MCP_OPENCODE_STATE_DIR/instances.json). Other tools may read it directly; this shape is a stable contract:
[
{
"runtime": "opencode", // always "opencode" for now
"sandbox": "srt", // "srt" when OS-sandboxed, else null
"port": 53817, // where the server listens, on 127.0.0.1
"pid": 41234, // the opencode serve process (or the srt wrapper, when sandboxed)
"mcpPid": 41200, // the mcp-opencode process that started it
"directory": "/Users/me/Projects/my-app",
"startedAt": "2026-10-02T12:04:34.453Z",
"password": "โฆ", // basic-auth password (user "opencode") for the server
// one entry per task, appended when task starts it
"sessions": [
{
"id": "ses_โฆ",
"title": "add health check",
"model": "github-copilot/gpt-4.1",
"startedAt": "2026-10-02T12:04:35.021Z",
// model switches so far, oldest first; empty until one happens
"fallbacks": [
{
"from": "github-copilot/gpt-4.1",
"to": "github-copilot/gpt-5",
"reason": "retry timeout after 90s (attempt 3: rate limited)",
"at": "2026-10-02T12:06:05.111Z",
},
],
},
],
},
]
Live state (busy or idle, last activity) is deliberately not in the file: read it from the server at http://127.0.0.1:<port> with the row's password. The file is written owner-only (0600) because it holds those passwords; list_instances leaves them out. A sandboxed row also carries an internal sandboxSettingsDir with the generated srt settings file; it is cleaned up on stop and is not part of the contract.
Environment variables
| Variable | Default | Purpose |
| ------------------------------------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| MCP_OPENCODE_URL | the background service | Use this opencode server for everything instead of the background service and its discovery |
| MCP_OPENCODE_PASSWORD | none | Password for MCP_OPENCODE_URL, when that server has one |
Truncated for display โ read the full file on GitHub.
Related Skills
taste-skill
117.6kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
Agent-Reach
112.7kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu โ one CLI, zero API fees.
ruflo
82.0k๐ The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
headroom
79.9kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit โ see the Safety scan above for what the skill file itself contains.
