opencode-deepseek-mcp
by wxxminjeong
README.md
# opencode-deepseek-mcp
Use **DeepSeek V4.1 Flash 1017** as subagents from **Claude Code**, billed to your **OpenCode Go** subscription
instead of your Claude usage.
Claude stays in charge. It hands bulky, well-specified work — tests, boilerplate, refactors, bulk edits, codebase
research — to DeepSeek workers that run in the foreground or in the background, can be steered mid-run, given follow-up
tasks, started in batches, and isolated on their own git worktree. Every result comes back with the files changed, a
git diffstat and each command the worker ran, so Claude can review before trusting it.
No other agent or CLI is involved: the server talks to the OpenCode API itself and implements the worker's tools
(`read_file`, `list_dir`, `glob`, `grep`, `write_file`, `edit_file`, `run_command`). Node is the only requirement.
## Tools
| Tool | What it does |
| --- | --- |
| `ds_run` | **Coding worker.** Edits files and runs commands (builds, tests, git status…) in a folder. `worktree: true` = own git worktree on branch `ds/<job id>`, committed when done. `no_commands: true` = edit only. |
| `ds_explore` | **Read-only worker.** Investigates a folder (read, list, glob, grep) and reports back. Safe to run several at once. |
| `ds_batch` | Start up to 10 `run`/`explore` jobs in one call. All are checked first (folders exist, no two editors in one folder unless they use worktrees); if any check fails, none start. |
| `ds_follow_up` | Give a **finished** job another task. It keeps its whole conversation — what it read and changed — so it doesn't start over. |
| `ds_message` | Steer a **running** job; picked up before its next step (if it was about to finish, it keeps going to handle it). |
| `ds_wait` | Wait for a job and return its report (returns early with recent activity on timeout — call again). |
| `ds_status` | List running jobs and this project's jobs from the last 2 hours (`all: true` = everything kept), or show one. `verbose: true` adds a step-by-step trace of every tool call. |
| `ds_cancel` | Stop a job. Running commands are killed; it reports "cancelled" only once the job has actually stopped. |
| `ds_ask` | One-shot question → text answer. `files` (absolute paths) are inlined by the server, so they don't eat Claude's context. |
| `ds_models` | List the models on your OpenCode Go plan and show which one is in use. |
`ds_run` and `ds_explore` take `background: true` to return a job id immediately. Foreground runs are jobs too, so they
show up in `ds_status`, can be cancelled, and hold the folder lock. Results include structured fields
(`changed_files`, `diffstat`, `commands`, `tokens`, `worktree`) alongside the text.
**`cwd` is optional:** leave it out and the worker uses the project folder Claude Code is working in; a relative path is
resolved against it.
**Notified when a job finishes, like a background subagent:** the plugin ships a monitor that Claude Code starts with
every session. When a job in the project finishes it posts one line — state, time, files changed, failed commands,
branch — and Claude collects it with `ds_wait`. Claude Code only starts plugin monitors in interactive terminal sessions
(not with `-p`, and not in some app/SDK hosts), so the server checks that the monitor is actually running (it leaves a
heartbeat in `~/.opencode-deepseek/monitors/`) before promising a notification. Otherwise — no plugin, no running
monitor, or a job in another folder — a background start returns a small `node "…/watch.mjs" "…/ds_xxxx.json"`
command for Claude to run with its Monitor tool, which gives the same one-line notification.
Coding and read-only workers are separate tools on purpose, so you can give them different permissions in Claude Code
(e.g. always allow `ds_explore`, ask before `ds_run`).
## Requirements
- Node.js 20.3+
- An [OpenCode Go](https://opencode.ai/docs/go/) subscription and an `oc_sk_…` API key from that workspace
- DeepSeek models are hosted outside the US/EU: in the OpenCode console set **Settings → Privacy → Regions → Global**,
or requests fail with HTTP 400
## Install
### As a Claude Code plugin (recommended)
```bash
claude plugin marketplace add wxxminjeong/opencode-deepseek-mcp
```
```bash
claude plugin install opencode-deepseek@opencode-deepseek
```
Then give it your API key — see [Setting the API key](#setting-the-api-key). The plugin adds:
- the MCP server above
- a **`deepseek-worker` subagent** (runs on Haiku) that briefs DeepSeek, waits, and reviews the result — so Claude can
delegate to DeepSeek exactly like to any other subagent
- a **`delegate-to-deepseek` skill** that tells Claude when delegating pays off
- **`/opencode-deepseek:ds <task>`** and **`/opencode-deepseek:ds-explore <question>`**
### As a plain MCP server
```bash
claude mcp add --scope user opencode-deepseek -- npx -y opencode-deepseek-mcp
```
The server also provides two prompts, shown as `/mcp__opencode-deepseek__ds` and `/mcp__opencode-deepseek__ds-explore`.
## Setting the API key
Use **one** of these. The server takes the first one it finds, in this order, and logs which one it used
(`API key from: …` in the MCP server log) — never the key itself.
1. **Plugin settings** (plugin installs; stored in your OS credential store, never in a settings file)
- Installed with `/plugin install` inside Claude Code: you are asked for the key when the plugin is enabled.
- Later, or after a command-line install: run `/plugin configure opencode-deepseek@opencode-deepseek` in
Claude Code, or pipe it in from a shell without it landing in your history:
```bash
printf '{"opencode_api_key":"%s"}' "$OPENCODE_API_KEY" | claude plugin configure opencode-deepseek@opencode-deepseek --values-stdin
```
2. **Environment variable `OPENCODE_API_KEY`** (works for plugin and plain installs) — leave the plugin setting empty
and export the key in your shell profile, or on Windows run `setx OPENCODE_API_KEY oc_sk_…` (picked up even by an
already-running Claude Code). `OPENCODE_GO_KEY` is accepted too.
3. **Per-server env** for a plain MCP install: `claude mcp add … -e OPENCODE_API_KEY=oc_sk_… -- npx -y opencode-deepseek-mcp`.
Simple, but the key is stored in plain text in `~/.claude.json`.
Restart Claude Code after changing the key. If none is found, every tool answers with these same instructions.
## Using it
Just ask Claude, e.g.:
> Have DeepSeek write unit tests for src/parser.ts in the background and make them pass. Meanwhile, let's look at the API design.
> Use ds_batch: one worker fixes the lint errors in src/api, another in src/ui, each in its own worktree.
> Send two DeepSeek explorers: one to find every place we read config, one to list all HTTP routes.
> That looks good — follow up on that job and also update the README.
Jobs are kept in memory and saved to `~/.opencode-deepseek/jobs/` (24 hours, newest 50). After a server restart the
records and reports are still there; a job that was running when the server stopped shows as `lost`, and
`ds_follow_up` needs the in-memory conversation, so it only works until the server restarts.
Only one editing job runs per folder (including nested folders) at a time; use `worktree: true` to run several on one
repository. Worktrees live in `~/.opencode-deepseek/worktrees/`; each result prints the commands to review, merge and
remove it.
## Configuration
Plugin users set the key and mode in the plugin's settings. For everything else, or for a plain MCP install, use
environment variables (`-e NAME=value` on `claude mcp add`):
| Variable | Default | Meaning |
| --- | --- | --- |
| `OPENCODE_API_KEY` | — | OpenCode Go key (`OPENCODE_GO_KEY` also accepted); see [Setting the API key](#setting-the-api-key) |
| `DS_MODEL` | `deepseek-v4.1-flash` | Model used by every tool — only change it when OpenCode Go ships a newer Flash |
| `DS_MAX_MODE` | `shell` | `shell` = `ds_run` may run commands, `edit` = edit only, `read` = only `ds_explore`/`ds_ask` (anything else → `read`) |
| `DS_MAX_STEPS` | `60` | Max agent steps per job (callers can ask for fewer, not more) |
| `DS_TASK_TIMEOUT_SEC` | `1800` | Wall-clock limit per job (callers can ask for less, not more) |
| `DS_TOKEN_BUDGET` | `2000000` | Tokens (in + out) one job may spend before it is told to wrap up and report |
| `DS_SHELL_TIMEOUT_SEC` | `120` | Default per-command timeout |
| `DS_DENY_COMMANDS` | — | Extra regexes to block, separated by `;;` (e.g. `docker;;kubectl`) |
| `DS_ALLOW_ALL_COMMANDS` | — | `1` turns off the built-in deny-list (`DS_DENY_COMMANDS` still applies) |
| `DS_STATE_DIR` | `~/.opencode-deepseek` | Where job records and worktrees are kept |
| `OPENCODE_BASE_URL` | `https://opencode.ai/inference/go/openai/v1` | OpenAI-compatible endpoint |
## Safety model — read this before using `shell` mode
- **Workspace confinement (file tools):** `read_file`/`write_file`/`edit_file` resolve paths (and links) and refuse
anything outside `cwd`; writes into `.git` are refused. `grep`, `glob` and `list_dir` never follow symlinks or junctions.
- **Mode enforcement:** the worker only gets the tools for its mode, and calls to other tools are rejected server-side.
- **Short command deny-list:** `run_command` only refuses what can't be undone or leaves your machine — wiping
root/home/drives, disk/boot tools, shutdown, `git reset --hard` / `git clean -f`, `git push`, `npm publish` /
`gh release`, and printing SSH/AWS/npm/`.env` credentials ([src/shell.ts](src/shell.ts)) — including when wrapped in
`bash -c "…"` or `powershell -Command "…"`. Words inside commit messages and `echo` text don't count. A blocked step is
skipped and reported, not retried. `DS_ALLOW_ALL_COMMANDS=1` turns the list off. It catches model **mistakes**; it is
not a defence against a malicious prompt (for example instructions planted in a repository the worker reads).
- **Secret scrubbing:** variables that look like secrets (`*_API_KEY`, `*TOKEN*`, `*SECRET*`, `*PASSWORD*`, `AWS_*`,
`OPENCODE_*`, `ANTHROPIC_*`, …) are removed from the environment of commands the worker runs.
- **`ds_ask` file guard:** refuses to upload SSH/GPG keys, cloud credentials, `.env` files, `.npmrc`, `*.pem`,
Claude/OpenCode auth files and similar, even through a link.
- **Non-interactive and cancellable:** stdin is closed, commands time out, cancel kills the whole process tree, and
running jobs and commands are stopped when the server exits.
**`shell` mode is not a sandbox:** commands that pass the list run with your user's permissions and can reach the
network and the rest of your disk. Use it in projects under version control and review the result, use `worktree: true`
to keep work off your checkout, run it in a container/VM for untrusted code, or set `DS_MAX_MODE=edit`.
On Windows, commands run in Windows PowerShell 5.1; elsewhere in `/bin/sh`.
## Development
```bash
npm install
npm run build # tsc → dist/
npm test # unit tests (no network)
npm run bundle # single-file server for the plugin → plugin/server/index.mjs
npm run smoke # live test against OpenCode Go (uses a little quota)
node scripts/smoke-features.mjs # live test of batch, worktrees, follow-up and trace
```
`plugin/server/index.mjs` is generated: rebuild it with `npm run bundle` and commit it whenever `src/` changes, since
plugin installs run it straight from the repository.
## License
MIT