Skip to content
Back to search

opencode-mcp

SkillWorks with Claude CodeGitHub

MCP server for OpenCode AI — 70 tools, 10 resources, 5 prompts. Use npx opencode-mcp with Claude Desktop, Claude Code, Cursor, Windsurf, or any MCP client.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/alaeddinemessadi--opencode-mcp/badge.svg)](/listings/alaeddinemessadi--opencode-mcp)

HTML

<a href="/listings/alaeddinemessadi--opencode-mcp"><img src="/api/listings/alaeddinemessadi--opencode-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install [OpenCode](https://opencode.ai/docs/) and start its server from your project:

opencode serve --hostname 127.0.0.1 --port 4096

If you use the TUI, start it with `opencode --port 4096` and share that server. Set `OPENCODE_BASE_URL` for another endpoint.

For Claude Code:

claude mcp add opencode -- npx -y opencode-mcp

For clients using an `mcpServers` configuration:

{
  "mcpServers": {
    "opencode": {
      "command": "npx",
      "args": ["-y", "opencode-mcp"]
    }
  }
}

Restart the client and call `opencode_setup`. Choose a provider from its configured providers, then use `opencode_provider_models` to select a model. Set `OPENCODE_DEFAULT_PROVIDER` and `OPENCODE_DEFAULT_MODEL` together or pass the selected IDs in each prompt call.

[Client-specific configuration](docs/configuration.md) includes VS Code, Windsurf, Continue, Zed, and Amazon Q. To test unreleased changes, [build from source](CONTRIBUTING.md) and configure your client to run `node` with the absolute path to `dist/index.js`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 127 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # opencode-mcp
  2. [![npm version](https://img.shields.io/npm/v/opencode-mcp)](https://www.npmjs.com/package/opencode-mcp)
  3. [![license](https://img.shields.io/github/license/AlaeddineMessadi/opencode-mcp)](LICENSE)
  4. [![node](https://img.shields.io/node/v/opencode-mcp)](https://nodejs.org/)
  5. **Delegate coding work to OpenCode from your MCP client.**
  6. opencode-mcp connects Claude, Cursor, VS Code, and other MCP clients to OpenCode's headless API. Ask questions, implement features, monitor background work, respond to questions and permissions, and review changes across projects.
  7. > Version 3.x requires **Node.js 22 or newer** and works with **OpenCode 1.x** (tested with 1.18.31 and 1.19.3). Support for OpenCode 2.x is planned for 4.0. Upgrading from 2.x? See the [migration notes](CHANGELOG.md#300---2026-09-16).
  8. ## Quick Start
  9. Install [OpenCode](https://opencode.ai/docs/) and start its server from your project:
  10. ```bash
  11. opencode serve --hostname 127.0.0.1 --port 4096
  12. ```
  13. If you use the TUI, start it with `opencode --port 4096` and share that server. Set `OPENCODE_BASE_URL` for another endpoint.
  14. For Claude Code:
  15. ```bash
  16. claude mcp add opencode -- npx -y opencode-mcp
  17. ```
  18. For clients using an `mcpServers` configuration:
  19. ```json
  20. {
  21. "mcpServers": {
  22. "opencode": {
  23. "command": "npx",
  24. "args": ["-y", "opencode-mcp"]
  25. }
  26. }
  27. }
  28. ```
  29. Restart the client and call `opencode_setup`. Choose a provider from its configured providers, then use `opencode_provider_models` to select a model. Set `OPENCODE_DEFAULT_PROVIDER` and `OPENCODE_DEFAULT_MODEL` together or pass the selected IDs in each prompt call.
  30. [Client-specific configuration](docs/configuration.md) includes VS Code, Windsurf, Continue, Zed, and Amazon Q. To test unreleased changes, [build from source](CONTRIBUTING.md) and configure your client to run `node` with the absolute path to `dist/index.js`.
  31. ## Choose a Workflow
  32. | Need | Tools |
  33. |---|---|
  34. | Setup and orientation | `opencode_setup`, `opencode_context`, `opencode_provider_models` |
  35. | Quick question or follow-up | `opencode_ask`, `opencode_reply` |
  36. | Start work and wait | `opencode_run` |
  37. | Work in the background | `opencode_fire`, then `opencode_check` or `opencode_wait` |
  38. | Recover or control a recorded job | `opencode_job_list`, `opencode_job_get`, `opencode_job_cancel` |
  39. | Resolve required input | `opencode_job_input`, permission and question tools |
  40. | Review the result | `opencode_review_changes`, `opencode_conversation` |
  41. ```javascript
  42. opencode_fire({
  43. directory: "/absolute/path/to/project",
  44. prompt: "Add input validation to POST /api/users and run the relevant tests",
  45. providerID: "<configured-provider>",
  46. modelID: "<available-model>"
  47. })
  48. // Save the returned job and session IDs; use them to monitor or resume observation.
  49. ```
  50. Async results distinguish `accepted`, `running`, `input_required`, `completed`, `failed`, `cancelled`, and `unknown`. An observation timeout returns current progress; it does not mean the task failed or was cancelled. Follow the returned state and IDs instead of assuming an absent busy status means success.
  51. Modern clients can use the MCP Tasks extension for `opencode_run`. Clients without that extension use ordinary tools, including `opencode_fire` and `opencode_check`. Task status is retrieved by polling; this package does not promise to wake an idle assistant with completion notifications.
  52. Tools retain readable text and provide structured results for clients that consume them. Prompt tools accept optional model variants and OpenCode structured-output formats. See the [generated tools reference](docs/tools.md) and [examples](docs/examples.md).
  53. ## Multi-Project Use
  54. Project-scoped tools accept `directory`: an absolute path **on the OpenCode server**. POSIX, Windows drive, and UNC paths are preserved across client operating systems. Relative paths are rejected; OpenCode checks existence and access.
  55. `opencode_project_init({path: "/absolute/local/project"})` creates or opens a directory on the **MCP host**. For remote OpenCode servers, create the project on that server instead. Authentication tools are global. Resources offer both static reads of the default project and [explicit project/session templates](docs/resources.md).
  56. Independent sessions do not isolate filesystem changes. Use separate project directories or Git worktrees when running overlapping coding tasks in parallel.
  57. ## Configuration
  58. All settings are optional; an OpenCode server must already be running by default.
  59. | Variable | Purpose |
  60. |---|---|
  61. | `OPENCODE_BASE_URL` | Server endpoint; defaults to `http://127.0.0.1:4096` |
  62. | `OPENCODE_SERVER_USERNAME`, `OPENCODE_SERVER_PASSWORD` | Optional server HTTP authentication |
  63. | `OPENCODE_SERVER_TOKEN` | Optional bearer token, e.g. an OpenChamber client token |
  64. | `OPENCODE_OPENCHAMBER_PASSWORD`, `OPENCODE_OPENCHAMBER_URL` | Sign in to an [OpenChamber](https://github.com/openchamber/openchamber)-fronted server |
  65. | `OPENCODE_OPENCHAMBER_CLIENT_ID` | Overrides the per-process OpenChamber client identifier; see [configuration](docs/configuration.md#openchamber) |
  66. | `OPENCODE_AUTO_SERVE` | Set to `true` to opt in to launching a local server |
  67. | `OPENCODE_DEFAULT_PROVIDER`, `OPENCODE_DEFAULT_MODEL` | Default prompt provider/model pair |
  68. | `OPENCODE_TOOL_PROFILE` | `full` (default) or a smaller `essential` tool set |
  69. | `OPENCODE_TASK_STORE` | Override the local directory for persisted job records |
  70. See [configuration](docs/configuration.md) for storage, permissions, and client setup. Auto-start only supports local loopback HTTP endpoints; custom OpenCode CLI flags require a manually started server.
  71. ## Development and Verification
  72. ```bash
  73. npm ci
  74. npm test
  75. npm run test:coverage
  76. ```
  77. Tests use local fixtures and do not require a model subscription. For controlled live checks against a local OpenCode server:
  78. ```bash
  79. npm run build
  80. node scripts/mcp-smoke-test.mjs
  81. ```
  82. Live smoke checks use a disposable project and owned session. Inference is opt-in with an explicitly selected provider and model. See [live verification and releases](docs/releasing.md) for scope, skipped capabilities, and publishing checks.
  83. ## Documentation
  84. - [Getting started](docs/getting-started.md)
  85. - [Configuration](docs/configuration.md)
  86. - [Tools reference](docs/tools.md)
  87. - [Resources](docs/resources.md) and [prompts](docs/prompts.md)
  88. - [Examples](docs/examples.md)
  89. - [Architecture](docs/architecture.md)
  90. - [Contributing](CONTRIBUTING.md) and [releasing](docs/releasing.md)
  91. [MIT license](LICENSE) · [OpenCode API](https://opencode.ai/docs/server/) · [Model Context Protocol](https://modelcontextprotocol.io/)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.