opencode-studio MCP server

---

For the experimental production build and loopback-only Docker setup, see production deployment. Remote use requires an authenticated reverse proxy; the Studio backend has no remote authentication.

opencode v2 configuration support

The compatibility work targets OpenCode 2.1.4 while retaining supported v1 config editing. Studio preserves the source format instead of migrating your setup:

• Native agents and commands, including ordered permission rules and agent Markdown files; MCP's servers, disabled, and global timeout settings.
• Native provider model maps and plugin package entries/options.
• Both v1 and v2 usage database layouts, with errors instead of false zero totals when a database cannot be read.
• A separate Raw Config → v2 CLI editor for global cli.json. It does not overwrite tui.json or silently prevent first-launch migration.

Important limits: v2 authentication is metadata-only in Studio. Use opencode auth for credential changes and account selection; legacy Studio auth pools are not applied to v2. V1 plugins need an actual API port, not a renamed config key. Native plugin runtime controls use plugin IDs, so edit those controls in Raw Config rather than relying on package-name toggles. Existing plugin code is never auto-converted.

See the compatibility verification notes and upstream migration guide. End-to-end native CLI agent discovery remains unverified; this is not a blanket compatibility claim. Keep a backup, and do not point v1 at native-v2-only configuration.

quickstart

option 1: public site + local backend (recommended)

npm install -g opencode-studio-server

visit opencode.micr.dev and click "Launch Backend" in the sidebar.

option 2: fully local

windows

quickstart.bat

macos / linux

chmod +x quickstart.sh && ./quickstart.sh

open http://localhost:1080

---

features

• mcp manager: toggle servers on/off, add new ones by pasting npx commands, delete unused configs
• profiles: isolated environments with separate configs, history, and sessions. switch instantly.
• skill editor: browse/edit skills, create from templates, import from url, bulk import multiple urls
• plugin hub: manage js/ts plugins, multiple templates (hooks, watchers, lifecycle), bulk import
• commands: browse and manage custom slash commands
• agents: manage custom agents with mode, model, tools, permissions (supports OMO format)
• usage dashboard: token costs, model breakdown, project stats from local message logs
• auth: login/logout per provider, save and switch between credential profiles
• github sync: push/pull config to a private github repo via gh cli
• backup/restore: export/import complete config including skills and plugins
• settings: general config, system prompt editor, oh my opencode model preferences
• i18n: internationalization support with Chinese (zh-CN) translation

---

i18n (Internationalization)

OpenCode Studio supports multiple languages:

• English (default)
• Chinese (zh-CN) - 完整中文翻译

Language can be switched via the language switcher in the sidebar. Selection is saved in cookies and persists across sessions.

To add a new language:

1. Create client-next/messages/{locale}.json (e.g., ja.json for Japanese)
2. Copy structure from en.json and translate all keys
3. Add locale to client-next/src/i18n/request.ts

---

how it works

flowchart LR
    A[Browser] -->|HTTP| B(Express API :1920+)
    B -->|Read/Write| C[~/.config/opencode/]
    C --> D[opencode.json]
    C --> E[skill/]
    C --> F[plugin/]

1. detect: server finds your opencode config directory automatically
2. read: loads opencode.json, skills, plugins, auth
3. edit: make changes through the ui
4. save: writes back to disk instantly

---

usage

route	actions
/mcp	toggle switches, add via npx command, search/filter
/profiles	create/switch isolated environments
/skills	create from template, bulk import, edit in monaco
/plugins	pick template, bulk import, click to edit
/commands	browse custom slash commands
/agents	manage agents with model, tools, permissions
/usage	token costs, model breakdown, project stats
/auth	login/logout, save/switch credential profiles
/settings	general, system prompt, github sync, oh my opencode models

---

bulk import

paste multiple raw github urls (one per line):

https://raw.githubusercontent.com/.../skills/brainstorming/SKILL.md
https://raw.githubusercontent.com/.../skills/debugging/SKILL.md
https://raw.githubusercontent.com/.../skills/tdd/SKILL.md

click fetch → preview with checkboxes → existing items unchecked → import selected

---

deep links

opencode studio supports deep links for one-click installs from external sites.

note: github blocks custom protocols like opencodestudio:// in user content. use a redirect page on github pages to bypass this.

protocol	description
opencodestudio://launch	start backend only
opencodestudio://launch?open=local	start backend + open localhost:1080+
opencodestudio://install-mcp?name=NAME&cmd=COMMAND	install mcp server
opencodestudio://import-skill?url=URL	import skill from url
opencodestudio://import-plugin?url=URL	import plugin from url

examples

add mcp server button (for docs/repos):

<a href="https://github.com/Microck/opencode-studio">
  <img src="https://img.shields.io/badge/opencode-studio-brown" alt="Add with OpenCode Studio" />
</a>

import skill button:

<a href="opencodestudio://import-skill?url=https%3A%2F%2Fraw.githubusercontent.com%2F...%2FSKILL.md">
  Import Skill
</a>

with environment variables:

opencodestudio://install-mcp?name=api-server&cmd=npx%20-y%20my-mcp&env=%7B%22API_KEY%22%3A%22%22%7D

url encoding

parameters must be url-encoded:

• spaces → %20
• / → %2F
• : → %3A
• { → %7B
• } → %7D

security

when clicking deep links, users see a confirmation dialog showing the command or url and a warning about trusting the source.

---

project structure

opencode-studio/
├── client-next/           # next.js 16 frontend
│   ├── src/app/           # pages (mcp, profiles, skills, plugins, auth, settings, usage)
│   ├── src/components/    # ui components
│   ├── src/i18n/          # internationalization config
│   ├── messages/          # translation files (en.json, zh-CN.json)
│   └── public/            # static assets
├── server/
│   └── index.js           # express api
├── quickstart.bat
├── quickstart.sh
└── package.json           # runs both with concurrently

config locations:

• opencode config: ~/.config/opencode/
• studio data: ~/.config/opencode-studio/
• profiles: ~/.config/opencode-profiles/

---

troubleshooting

problem	fix
"opencode not found"	ensure ~/.config/opencode/opencode.json exists
port conflicts	both services auto-detect available ports (backend 1920+, frontend 1080+)
skills not showing	check ~/.config/opencode/skill/ has SKILL.md files
bulk import fails	ensure urls are raw github links
"Launch Backend" not working	run npm install -g opencode-studio-server first
protocol handler not registered	run opencode-studio-server --register as admin
github sync not working	run gh auth login first
agents not showing (OMO)	ensure oh-my-openagent.json exists with agents field

---

sponsorship

sponsorships are welcome. contact contact@micr.dev to discuss supporting the project.

---

license

mit

---