opencode-mcp

Name: opencode-mcp
Author: Alaeddine Messadi

Hands coding tasks from an MCP client to a running OpenCode server and tracks them to completion

By Alaeddine Messadi (individual) TypeScript Local · stdio Developer tools AI and ML

GitHub npm Website

68 popularity score ★ 161 ↓ 25k/wk

Connect your client

Local (npm)

Add in one click

Add to Cursor Add to VS Code Add to LM Studio Add to Goose

Opens the app, which asks before it adds the server.

Or add it by command or config

Claude CodeTerminal

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

Claude Desktopclaude_desktop_config.json

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

Cursor~/.cursor/mcp.json

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

VS Code.vscode/mcp.json

{
  "servers": {
    "opencode": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "opencode-mcp"
      ]
    }
  }
}

Codex~/.codex/config.toml

[mcp_servers.opencode]
command = "npx"
args = ["-y", "opencode-mcp"]

Gemini CLITerminal

gemini mcp add --scope user opencode npx -- -y opencode-mcp

Settings 12

Set together: basic auth
`OPENCODE_BASE_URL`	Optional: OpenCode server address, or an OpenChamber proxy's /api path. Default `http://127.0.0.1:4096`.
`OPENCODE_SERVER_TOKEN` secret	Optional: Bearer token sent instead of basic auth, such as an OpenChamber client token. It is not renewed.
`OPENCODE_OPENCHAMBER_PASSWORD` secret	Optional: OpenChamber UI password, swapped for a client token on first use. For OpenChamber sign-in.
`OPENCODE_OPENCHAMBER_URL`	Optional: OpenChamber origin that serves /auth/session, when it differs from the base URL's origin. For OpenChamber sign-in.
`OPENCODE_OPENCHAMBER_CLIENT_ID`	Optional: Fixed client ID so restarts reuse one OpenChamber device entry. A random one is made per process. For OpenChamber sign-in.
`OPENCODE_AUTO_SERVE`	Optional: Set exactly to true to let it start a local OpenCode server. Default `false`.
`OPENCODE_TOOL_PROFILE`	Optional: full (87 tools) or essential (25 tools). Other values stop startup. Default `full`.
`OPENCODE_TASK_STORE`	Optional: Folder for job records instead of the default state folder.
`OPENCODE_SERVER_USERNAME`	Optional: Username for OpenCode HTTP basic auth. Default `opencode`.
`OPENCODE_SERVER_PASSWORD` secret	Optional: Password for OpenCode HTTP basic auth, matching the server's.
Set together: default model
`OPENCODE_DEFAULT_PROVIDER`	Optional: Default provider ID for prompts. Ignored unless the model is set too.
`OPENCODE_DEFAULT_MODEL`	Optional: Default model ID for prompts.

What it does

This is a stdio bridge between an MCP client such as Claude Code or Cursor and the HTTP API of OpenCode, the open-source coding agent. It writes no code of its own. Your assistant sends prompts to OpenCode sessions, and OpenCode works on the project with whatever model provider it is set up with.

The core tools cover quick questions with follow-ups, plus background jobs you start now and check on later. Job records sit on disk, so a job survives a timeout or a client restart. Other tools answer OpenCode's questions and permission prompts, review diffs and session history, read project files, edit OpenCode's config and provider keys, and drive the OpenCode terminal UI.

The npm description still counts 70 tools and 5 prompts. The source registers 87 tools in the default `full` profile and 6 prompts, along with 14 resources where npm says 10. `OPENCODE_TOOL_PROFILE=essential` trims the list to 25 delegation and monitoring tools, and any other value stops the server at startup. `opencode_run` watches a task for 600 seconds unless `maxDurationSeconds` asks for more, up to 3600.

Besides HTTP basic auth it can send a bearer token. It can also sign in to a server behind OpenChamber with the UI password and keep the client token it gets back in memory. Job records live in `$XDG_STATE_HOME/opencode-mcp/tasks` (or `~/.local/state/opencode-mcp/tasks` when that is unset) and expire 24 hours after creation. Expiry does not stop the OpenCode session behind them.

What it needs

Runtime	Node.js 22+
Runs on	macOS, Windows, Linux
OpenCode model provider	Paid planPrompts need at least one provider set up in OpenCode, often a paid API account
Also	OpenCode 1.x server running, by default at http://127.0.0.1:4096

Install OpenCode 1.x (the docs name 1.18.31 and 1.19.3 as tested) and start its server with `opencode serve --hostname 127.0.0.1 --port 4096`, or start the TUI with `opencode --port 4096`. Setting `OPENCODE_AUTO_SERVE=true` lets it launch a local server itself. For a server behind OpenChamber, point `OPENCODE_BASE_URL` at its `/api` path and use OpenChamber 1.12 to 1.24 for password sign-in.

Limits

Not covered Speaks the OpenCode 1.x API only. OpenCode 2.x support is planned for a later major release.
Limit OPENCODE_AUTO_SERVE starts a server only for a loopback http address with no path. Remote servers are started by hand.
Limit `directory` must be an absolute path on the OpenCode server. Relative paths are refused.
Not covered `opencode_project_init` creates folders only on the machine running this server, and refuses system roots such as /, /etc and /usr.
Limit Sessions in one folder share its files, so overlapping parallel tasks need separate folders or git worktrees.
Limit Completion is found by polling. An idle client is not woken when a job ends.
Size cap `opencode_run` watches for 600 seconds by default, at most 3600. A timeout leaves the job running.
Not covered OpenChamber password sign-in needs OpenChamber 1.12 to 1.24. With 2.0 or newer sign-in works but the tools then fail.
Rate limit OpenChamber locks out an IP for 15 minutes after 10 failed sign-ins. A rejected password is not tried again until restart.
Limit Issue #18 reports hangs when a second OpenCode server shares the same storage. A shared, explicitly set server is advised.

Auto-start (`OPENCODE_AUTO_SERVE`) works only for loopback HTTP addresses and takes no custom OpenCode flags. `directory` must be an absolute path on the OpenCode server. `opencode_project_init` can only create folders on the machine running the MCP server, not on a remote OpenCode host. Sessions in the same folder are not isolated from each other, so overlapping parallel tasks need separate folders or git worktrees. Completion is found by polling: idle clients are not notified. An observation timeout means the job is still running, not that it failed. The docs point to an open issue (#18) about hangs when a second OpenCode server shares the same storage.

Who it suits

Suits developers who already use OpenCode and want an MCP client to hand it longer coding jobs, perhaps across several projects, and check on them later. Teams that reach OpenCode through OpenChamber or a token-protected endpoint can now connect too. With 87 tools in the default profile it can crowd a client's tool list, so most people will want the `essential` profile. If you do not run OpenCode, a file-system or git server is a simpler fit. It is a community project, not one from the OpenCode team.

Tools 60 of 87

30 only read, 29 change things, 1 can delete or overwrite. A ? marks an optional parameter.

opencode_ask changes: Opens a new session, sends one prompt and returns the answerprompt: stringtitle?: stringproviderID?: stringmodelID?: stringvariant?: stringagent?: stringsystem?: stringformat?: objectdirectory?: string
opencode_reply changes: Sends a follow-up prompt to an existing sessionsessionId: stringprompt: stringproviderID?: stringmodelID?: stringvariant?: stringagent?: stringformat?: objectdirectory?: string
opencode_run changes: Sends a task and watches it until done, with a job ID to resume fromprompt: stringsessionId?: stringtitle?: stringproviderID?: stringmodelID?: stringvariant?: stringagent?: stringdirectory?: stringformat?: objectmaxDurationSeconds?: number
opencode_fire changes: Starts a background job and hands back its job, session and message IDs straight awayprompt: stringsessionId?: stringtitle?: stringproviderID?: stringmodelID?: stringvariant?: stringagent?: stringdirectory?: stringformat?: object
opencode_check: Shows where a job or session stands: status, pending input, todos, changed filessessionId?: stringjobId?: stringmessageId?: stringdetailed?: booleandirectory?: string
opencode_wait: Watches a session or job until it finishes, needs input, or the wait runs outsessionId?: stringjobId?: stringmessageId?: stringtimeoutSeconds?: numberpollIntervalMs?: numberdirectory?: string
opencode_job_get: Reads one job record with its pending input and resultjobId: string
opencode_job_cancel changes: Aborts the session a job runs in, stopping other work there toojobId: string
opencode_job_list: Lists the job records kept on this machinelimit?: number
opencode_job_input changes: Answers a job's pending questions or permission requestsjobId: stringresponses?: array
opencode_setup: Checks the server and provider setup, and can open a project folderdirectory?: string
opencode_context: Gives project, path, VCS state, config and agents in one calldirectory?: string
opencode_status: Short dashboard of server health, providers, session counts and VCSdirectory?: string
opencode_conversation: Prints a session's message historysessionId: stringlimit?: numberdirectory?: string
opencode_sessions_overview: Lists sessions with their titles and statusdirectory?: string
opencode_review_changes: Formats the file diffs a session produced for reviewsessionId: stringmessageID?: stringdirectory?: string
opencode_provider_test changes: Sends a throwaway prompt to see whether a provider answersproviderId: stringmodelID?: stringvariant?: stringformat?: objectdirectory?: string
opencode_question_list: Lists questions OpenCode is waiting onsessionId?: stringdirectory?: string
opencode_question_reply changes: Answers a pending questionrequestId: stringanswers: arraydirectory?: string
opencode_question_reject changes: Turns down a pending questionrequestId: stringdirectory?: string
opencode_permission_list: Lists permission requests holding up sessionsdirectory?: string
opencode_session_permission changes: Grants or refuses one of a session's permission requestsid: stringpermissionID: stringreply: enumdirectory?: string
opencode_session_list: Lists sessions in the projectdirectory?: string
opencode_session_create changes: Creates a session, optionally under a parent sessionparentID?: stringtitle?: stringdirectory?: string
opencode_session_abort changes: Stops a session that is runningid: stringdirectory?: string
opencode_session_delete deletes: Deletes a session and its dataid: stringdirectory?: string
opencode_session_diff: Returns the diff a session madeid: stringmessageID?: stringdirectory?: string
opencode_session_fork changes: Copies a session, optionally from a chosen messageid: stringmessageID?: stringdirectory?: string
opencode_session_revert changes: Undoes a message and its file changes in a sessionid: stringmessageID: stringpartID?: stringdirectory?: string
opencode_session_share changes: Publishes a session through OpenCode sharingid: stringdirectory?: string
opencode_session_init changes: Has OpenCode study the project and write AGENTS.mdid: stringmessageID: stringproviderID: stringmodelID: stringvariant?: stringdirectory?: string
opencode_session_summarize changes: Has a chosen model summarise a sessionid: stringproviderID: stringmodelID: stringvariant?: stringdirectory?: string
opencode_message_send changes: Sends a prompt to a session and waits for the answersessionId: stringtext: stringproviderID?: stringmodelID?: stringvariant?: stringagent?: stringnoReply?: booleansystem?: stringformat?: objectdirectory?: string
opencode_message_send_async changes: Sends a prompt without waiting for the answersessionId: stringtext: stringproviderID?: stringmodelID?: stringvariant?: stringagent?: stringformat?: objectdirectory?: string
opencode_command_execute changes: Runs a slash command such as /undo in a sessionsessionId: stringcommand: stringarguments?: stringagent?: stringproviderID?: stringmodelID?: stringvariant?: stringdirectory?: string
opencode_shell_execute changes: Runs a shell command through an OpenCode sessionsessionId: stringcommand: stringagent: stringproviderID?: stringmodelID?: stringdirectory?: string
opencode_file_list: Lists files and folders at a pathpath?: stringdirectory?: string
opencode_file_read: Returns a file's contentspath: stringdirectory?: string
opencode_file_status: Shows files changed under version controldirectory?: string
opencode_find_file: Fuzzy-finds files or folders by namequery: stringtype?: enumsearchDirectory?: stringlimit?: numberdirectory?: string
opencode_find_symbol: Finds functions, classes and other symbols by namequery: stringdirectory?: string
opencode_find_text: Searches project files with a regexpattern: stringdirectory?: string
opencode_config_get: Reads the OpenCode configurationdirectory?: string
opencode_config_update changes: Changes fields in the OpenCode configurationconfig: objectdirectory?: string
opencode_auth_set changes: Stores a provider credential such as an API key in OpenCodeproviderId: stringtype: stringkey: string
opencode_provider_list: Lists providers and whether each is connecteddirectory?: string
opencode_provider_models: Lists the models one provider offersproviderId: stringlimit?: numberdirectory?: string
opencode_provider_oauth_authorize changes: Starts a provider's OAuth sign-inproviderId: stringmethod?: numberinputs?: object
opencode_tui_submit_prompt changes: Submits what is in the terminal UI prompt boxdirectory?: string
opencode_tui_append_prompt changes: Adds text to the terminal UI prompt boxtext: stringdirectory?: string
opencode_project_init changes: Creates or opens a folder on the machine running this serverpath: string
opencode_project_list: Lists projects the OpenCode server knowsdirectory?: string
opencode_events_poll: Collects recent project or global events for a short timedurationMs?: numbermaxEvents?: numberdirectory?: stringscope?: enum
opencode_health: Reports server health and versiondirectory?: string
opencode_agent_list: Lists the agents OpenCode offers and their modesdirectory?: string
opencode_instance_dispose changes: Shuts down the current OpenCode instancedirectory?: string
opencode_mcp_add changes: Adds another MCP server to OpenCode while it runsname: stringconfig: objectdirectory?: string
opencode_mcp_status: Shows the state of MCP servers set up in OpenCodedirectory?: string
opencode_lsp_status: Shows language server statusdirectory?: string
opencode_vcs_info: Returns branch and remote details of the projectdirectory?: string

Resources 14

opencode://project/current: The current project
opencode://config: OpenCode configuration
opencode://providers: Providers and their models
opencode://agents: Available agents
opencode://commands: Available slash commands
opencode://health: Server health and version
opencode://vcs: Version control state
opencode://sessions: Sessions in the project
opencode://mcp-servers: MCP servers set up in OpenCode
opencode://file-status: Changed files in the project
opencode://projects/{directory}/current: A named project, by its URL-encoded server path
opencode://projects/{directory}/sessions: Sessions of a named project
opencode://projects/{directory}/sessions/{sessionId}: One session of a named project
opencode://projects/{directory}/sessions/{sessionId}/messages: Messages of one session in a named project

Prompts 6

opencode-code-review: Reviews the changes a session made
opencode-debug: Starts a debugging session
opencode-project-setup: Gets oriented in a new project
opencode-implement: Has OpenCode build a feature or make changes
opencode-best-practices: Guide to picking tools, background jobs and provider setup
opencode-session-summary: Summarises what happened in a session

Popularity

68 popularity score, on our list (the bar is 36)

★ 161 ↓ 25k/wk

GitHub stars	161	26.5 points
Stars in 30 days	+16	6.2 points
npm downloads, last week	25,387	35.2 points

Measured 2026-11-08. How the score works.

Where it is published

Code	alaeddinemessadi/opencode-mcp ★ 161
npm	opencode-mcp 3.1.0, 2026-10-29

What it can reach

Runs	On your machine
Reaches	Your code, Files on your machine, Runs shell commands, The internet, Your account at a service
Changes things	Yes: it can write, send, create or delete
Sign-in	None
Licence	MIT (npm)
Last code change	2026-10-29

Runs locally and calls an OpenCode server over HTTP (127.0.0.1:4096 unless `OPENCODE_BASE_URL` names another host). Sign-in is optional: basic auth, a bearer token (`OPENCODE_SERVER_TOKEN`), or an OpenChamber password swapped for a client token held in memory. The docs warn that these grant the same access as the OpenChamber UI. Through OpenCode its tools can change project files, run shell commands (`opencode_shell_execute`), delete or revert sessions, publish a session by sharing it, edit OpenCode's config, store provider API keys, add MCP servers and shut down the instance. Prompts go to whichever model provider OpenCode uses. `opencode_job_input` never approves a request by itself. Job records with results are written to a local state folder.

Over time

GitHub stars 161 +16 (+11 %)

161145

8 Oct 20268 Nov 2026

npm downloads a week 25k +25k (+5467 %)

26k67

16 Feb 20268 Nov 2026

Before the site measured it, read from npm's daily download counts.

Popularity score 68 +7 (+11 %)

6846

8 Oct 20268 Nov 2026

What is rising across the directory

Sources

Page checked 2026-11-02.

Badge for your README

Shows this server's rank in its category, and stars for a server that runs on your machine. It updates every hour.

MarkdownREADME.md

[![opencode-mcp on EveryMCPServer](https://everymcpserver.com/badge/opencode-mcp.svg)](https://everymcpserver.com/servers/opencode-mcp)

Connect your client

Add in one click

Or add it by command or config

Settings 12

What it does

What it needs

Limits

Who it suits

Tools 60 of 87

Resources 14

Prompts 6

Similar servers

Codex MCP Server

OpenWork MCP Gateway

CodeQL Development MCP Server

Code Index MCP

Crewly

1MCP