Plugin developer guide

Ship MCP servers for OpenCode users and get listed in its ecosystem

By HOL · Reviewed by Michael Kantor on

Direct answer

OpenCode loads MCP servers from the mcp key of opencode.json. Run hol-guard plugin package --runtimes opencode to write that file from your plugin, with environment variables kept as {env:NAME} references, and publish it in your README. OpenCode plugins proper are JavaScript or TypeScript modules loaded from npm or a plugins folder. To be listed on the OpenCode ecosystem page, open a pull request; awesome-opencode is a community list.

Who this is for

MCP server and plugin authors whose users run OpenCode.

Good fit

  • An MCP server with a Claude Code or Codex plugin already
  • A README that shows install config for several runtimes
  • A project heading for the OpenCode ecosystem list

Not a fit

  • OpenCode plugins written as JavaScript or TypeScript modules, which the Kit does not generate

Steps

  1. 1.Install HOL Guard

    The Plugin Kit ships inside HOL Guard. It needs Python 3.10 or newer and pipx. If Guard is already installed, upgrade it so the Kit commands below are available.

    pipx install hol-guard
pipx upgrade hol-guard
hol-guard --version

  2. 2.Check the plugin

    The check detects every manifest in the folder, lists skills and MCP servers, and reports what each runtime would reject. It exits 0 when the plugin passes, 1 when it has errors and 2 when it could not run. It reads only the folder, runs no commands and makes no network calls.

    hol-guard plugin check .

  3. 3.Write the OpenCode config

    Packaging for OpenCode writes opencode.json with your MCP servers under mcp. Users merge it into their own opencode.json and set the variables it references.

    hol-guard plugin package . --runtimes opencode --out dist/hol-plugin

  4. 4.Publish it with your project

    Commit the generated config or show it in the README next to the other runtimes. If you also ship an OpenCode plugin module, publish it to npm so users can add it to the plugin array.

  5. 5.Get listed

    The OpenCode ecosystem page takes additions by pull request. awesome-opencode and opencode.cafe also collect community projects.

  6. 6.Add the install block to your README

    hol-guard plugin links --block prints a README block between hol-install-block markers: one hol-guard plugin install command, how to get HOL Guard, and each runtime's own install commands for the runtimes the repository already supports. Paste it into the README; HOL finds it on its next scan and shows the install count on your listing once enough installs are reported.

    hol-guard plugin links . --block

  7. 7.Connect the repository on HOL

    Open the connect page with your repository to verify ownership and claim the listing. hol-guard plugin links prints the same link with the repository filled in.

    hol-guard plugin links .

Limitations

  • The Kit writes MCP config only; skills, commands, agents and hooks do not carry to OpenCode.
  • OpenCode installs npm plugins with Bun at startup, so review a plugin module like any dependency.
  • A listing, a passing check or a marketplace review is not a safety guarantee. HOL shows its scan evidence on the listing so users can judge for themselves.

Questions

Is an OpenCode plugin the same as an MCP server?

No. An OpenCode plugin is a JavaScript or TypeScript module that hooks into OpenCode events. MCP servers are configured separately under mcp in opencode.json.

Where does OpenCode load local plugins from?

From .opencode/plugins/ in the project and ~/.config/opencode/plugins/ globally, at startup.

Sources

Related guides

List it on HOL

Connect the repository to verify ownership and claim the listing. New plugins can be submitted for free.

Connect your plugin repository