# opencode-workbench [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/simonmak-ascent/opencode-workbench  
**GitHub Stars:** 1  
**npm Downloads (last month):** 2251  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/opencode-workbench

## Description
Provision an OpenCode workbench and MCP stack on any Linux box, local or over SSH.

## Tools
Capabilities this server exposes over MCP:

- **describe_workbench** — Describe this MCP server from its bundled profile without contacting any target or making a network call: repository URL, the default component set, components grouped by tier (required/core/optional), and optional MCP add-ons. It takes no parameters, is always safe, and returns instantly. Use it first to resolve a component id for install_component/remove_component/update_component or to see available add-ons; use inspect_target for a machine's live state.
- **inspect_target** — Probe one Linux machine — this host (`local`) or a remote host over SSH (`ssh`) — and report its OS, kernel, architecture, package manager, Node/npm, OpenCode, Docker, and per-tool detection flags, plus the names (never values) of credentials present. Read-only: it runs one shell probe as the target user (over SSH when `mode:ssh`), installs nothing, writes nothing, contacts no external service, and can take a few seconds per hop. Parameter semantics: `target.mode` selects local vs ssh (default `local`); `target.host` is required only for ssh; `target.user` defaults to the ssh config/current user; `target.cwd` sets the directory for relative checks; `target.port`/`identityFile` pass straight to ssh. Use it to see what a clone would touch, then plan_clone to turn that into an ordered plan and apply_clone to perform it.
- **plan_clone** — Return a read-only plan for a target: compare it against the Workbench profile and list each component as `install`, `present`, or `manual`, with the commands that would run. It still runs a detection probe on the target (same access as inspect_target) but clones nothing and writes nothing. Parameter semantics: `components` restricts the diff to those ids (default: required+core); `workspace` sets the expected profile path on the target (default `~/opencode-workbench`); `profileUrl` overrides the git remote. Use it to preview before apply_clone, which performs the changes.
- **apply_clone** — Apply the Workbench profile to a target: clone the repo and install missing components (OpenCode CLI, Node/pnpm, MCP servers, skills, plugins, optional Docker). It OVERWRITES `<home>/.config/opencode/opencode.json`, copies `AGENTS.md`, resets an existing profile repo to `origin/main`, and runs global installs that need write permission (plus SSH for `mode:ssh`) and can take minutes. Writes a names-only `~/.env.workbench` (mode 600); never secret values. Consent-gated and idempotent: without `confirm:true` it returns the plan and changes nothing. Parameter semantics: `components` defaults to required+core; `workspace` defaults to `~/opencode-workbench`; `skipRepo` skips the clone/update; `profileUrl` overrides the git remote; `dryRun` returns the plan. To preview only, use plan_clone.
- **verify_clone** — Re-check a target after a clone: return a per-component `present`/`missing` list plus whether `opencode.json` and `~/.env.workbench` exist. Read-only and idempotent: it runs a detection probe (SSH or local) and checks files, writing nothing. `target` selects the machine (`local` or SSH) and its `home` is where the `opencode.json` and `~/.env.workbench` checks run; `components` restricts the check to those ids (omit it to check every component, the default); `workspace` sets the profile path used by component checks. Use it after apply_clone and after component changes; for a pre-clone preview use plan_clone.
- **install_component** — Install a single Workbench component by id (e.g. `node`, `opencode`, `npm-mcps`, `skills`) on a target; `component` must be an id from describe_workbench. Overwrites that component's files when present (e.g. `skills`/`plugins` replace the copies under `<home>/.config/opencode`); global installs need write permission and can take minutes. Idempotent and consent-gated: without `confirm:true` it returns the plan. Parameter semantics: `component` is required; `workspace` defaults to `~/opencode-workbench`; `confirm` defaults to false (plan only). Use it for one targeted component; use apply_clone to install the full default set.
- **remove_component** — Uninstall one Workbench component by id from a target — the inverse of install_component — for a bounded, documented subset with an automated uninstall (e.g. `opencode`, `pnpm`, `npm-mcps`, `skills`, `docker-containers`); `component` must be an id from describe_workbench. Idempotent: an already-absent component reports `absent`; a component with no automated uninstall (system packages such as git/curl/node) reports `manual`. Destructive and consent-gated: without `confirm:true` it returns a preview and changes nothing, and it deletes only that component's files — never `opencode.json` or the profile repo. Parameter semantics: `workspace` sets the profile path some removals need; `dryRun` reports without changing. Use it to tear down one component; for several, call it per id.
- **update_component** — Update one Workbench component in place by id: re-run its install script to fetch the current version (e.g. `opencode` re-runs the official installer; `npm-mcps` reinstalls the latest globals). It OVERWRITES the component's files, needs write permission, and can take minutes for global installs; the resolved version may change. Parameter semantics: `component` must be an id from describe_workbench; `workspace` defaults to `~/opencode-workbench`; `dryRun` previews; `confirm` defaults to false — set `confirm:true` to apply. For the whole profile use apply_clone.
- **list_required_credentials** — List the credentials the profile references, which the target already provides, and how to acquire each missing one. Value-blind: it reads only whether each env var is set — no values, no network, no writes — via one read-only probe. Parameter semantics: `target` selects the machine (`local` or SSH) and its `home` sets the returned `template` path and the env file the presence check reads; there are no other parameters. Returns `present`/`missing` var-name arrays plus one guidance record per credential (`var`, `purpose`, `url`, `method`, `command`). Use it after plan_clone to see what would degrade; act on one credential with run_auth_flow.
- **run_auth_flow** — Return the acquisition plan for one credential on a target: the provider URL, the exact non-interactive command when one exists (e.g. `opencode auth login`, `opencode mcp auth vercel`, `gh auth login`), and whether it is already present. Read-only and value-blind: it emits guidance and re-checks presence with one read-only probe; it does not run the commands or handle secret values. Parameter semantics: `var` must be an env var name returned by list_required_credentials (unknown names error); `target` selects the machine and its `home` is where the value should be written. Use it for a single credential; it does not replace that listing.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "opencode-workbench": {
    "command": "npx",
    "args": ["-y","@simonmak-ascent/opencode-workbench"]
  }
}
```

## Documentation

## What opencode-workbench does

The opencode-workbench MCP server installs the repository’s workstation profile on a Linux target. The profile includes OpenCode configuration, MCP server configuration, reusable agent skills, Docker-based infrastructure, command-line tools, and operational documentation. It is intended to make a development environment reproducible from the repository’s versioned configuration.

The target can be the machine running the connector or another Linux machine accessed through SSH. The setup can include PostgreSQL 16 and Browserless Chromium through Docker, along with tools such as pandoc, jq, Miller, sqlite3, the GitHub CLI, and Playwright Chromium, as described by the repository.

This project belongs to the 💻 Developer Tools category and is most relevant when a team needs a repeatable OpenCode workstation, a documented recovery path, or a way to bootstrap a fresh Linux box.

## How it works

The opencode-workbench MCP server exposes a staged clone lifecycle. `inspect_target` reports information about the target, including its operating system, available toolchain, Docker state, and existing configuration. `plan_clone` then produces the proposed components and a preview of privileged commands.

`apply_clone` performs the changes only when called with `confirm: true`. Without that confirmation, it returns the plan and does not modify the machine. Afterward, `verify_clone` checks the result and reports pass/fail information together with missing credentials.

The connector does not read or transmit secret values. During provisioning it writes an empty `~/.env.workbench` template for the operator to complete. Missing model or service credentials do not necessarily prevent the workstation from booting: unavailable credential-dependent MCP servers are disabled and reported, while the setup can use the OpenCode Zen free floor when no model key is present.

## Setup and configuration

For a local OpenCode registration, configure the server to run through `npx -y @simonmak-ascent/opencode-workbench`. The example configuration enables the server and sets a 600-second timeout. The project also publishes a remote MCP endpoint at `POST https://opencode-workbench.simonmak.com/mcp`.

After registration, ask the OpenCode agent to run `inspect_target`, `plan_clone`, `apply_clone` with confirmation, and `verify_clone`. Use `{ "mode": "local" }` for the current machine or `{ "mode": "ssh", "host": "...", "user": "..." }` for an SSH target. `list_required_credentials` identifies keys still needed and explains how to obtain them; `run_auth_flow` is available for credential-related flows.

Run `bash scripts/selftest/run-selftest.sh` to perform the repository’s self-test.

## Tools and capabilities

The documented tool surface includes:

- `describe_workbench` for discovering the available workbench profile.
- `inspect_target` for examining the destination machine.
- `plan_clone` for generating a change plan and privileged-command preview.
- `apply_clone` for applying a confirmed plan.
- `verify_clone` for checking installation results.
- `install`, `remove`, and `update_component` for component management.
- `list_required_credentials` and `run_auth_flow` for credential-related tasks.

The server supports both local and SSH-based clone operations. Its profile covers 35 configured MCP servers, with 33 enabled and 2 disabled in the referenced configuration, plus 45 reusable skills and OpenCode plugins. Exact components can change with the repository’s source-of-truth configuration.

## Limitations and notes

The target must be a Linux machine, and SSH mode requires a reachable host and usable SSH access. Applying a clone can run privileged commands, so the confirmation step should be reviewed rather than treated as an automatic installation approval.

The connector intentionally does not handle secret values. Operators must fill in the generated environment template and provide any required credentials separately. Services without credentials are disabled and reported rather than guaranteed to work immediately.

Other MCP clients may require their own local or remote MCP configuration format.

_Full upstream README: https://allmcps.com/mcp/opencode-workbench/readme_