codex-mcp-opencode

中文 | English

A project-local MCP bridge: Codex plans; OpenCode executes in the project.

项目内 MCP 桥接器：Codex 负责规划，OpenCode 在项目内执行。

Codex Desktop  ->  codex-mcp-opencode  ->  OpenCode Server/SDK  ->  Current project
    planning          thin control plane       sessions/models         code and tools

中文说明

它解决什么问题

codex-mcp-opencode 让 Codex Desktop 作为项目的规划者和调度者，而 OpenCode 作为实际执行者。Codex 只需向 OpenCode 下达简短、具体的工作指令；OpenCode 从启动它的当前项目目录中自行读取代码、配置和已有上下文。

它不是第二个项目记忆系统，也不是 API Key 管理器，更不会向模型重复发送源码或项目摘要。模型、供应商和凭据始终由 OpenCode 自己管理。

核心特性

前置条件

1. Node.js 20 或更高版本。

2. opencode 已安装、可在 PATH 中调用，并已在 OpenCode 内配置模型和凭据。

3. OpenCode 中的目标模型必须设置 limit.context 为 550000。

4. OpenCode 中必须开启原生压缩和裁剪：compaction.auto: true、compaction.prune: true。

桥接器会在执行前检查模型上报的 limit.context，不是 550000 就拒绝运行。这样 DeepSeek 不会被推到约 600k 后才压缩。这个值需要在 OpenCode 配置中设置，MCP 不会改写供应商、模型或 API Key。

通用的 OpenCode 配置形状如下，请将占位符替换为自己的供应商和模型：

{
  "provider": {
    "<provider-id>": {
      "models": {
        "<model-id>": {
          "limit": { "context": 550000, "output": 32000 }
        }
      }
    }
  },
  "compaction": { "auto": true, "prune": true }
}

给其他用户的安装与接入

本仓库当前可直接从 GitHub 安装，尚未发布到 npm。使用者不需要修改源码、填写 API Key，也不需要在工具调用中提供项目路径。

方式一：直接在 Codex MCP 配置中使用 GitHub（推荐）

将以下命令配置为 Codex 的 stdio MCP 服务：

command: npx
args:    --yes github:Ichikawashadow/codex-mcp-opencode

Codex 必须从当前打开的目标项目目录启动该命令。npx 从 GitHub 获取包时会运行 prepare 自动构建；之后 OpenCode 仍由 MCP 在当前项目内拉起。

方式二：克隆后本地安装

git clone https://github.com/Ichikawashadow/codex-mcp-opencode.git
cd codex-mcp-opencode
npm ci
npm run build

然后将下面的程序配置为 Codex 的 stdio MCP 服务：

command: node
args:    <安装目录>/dist/index.js

这里的 <安装目录> 是 MCP 自身的本机安装位置，不是目标项目路径。它只应存在于用户自己的 Codex 配置中，不能写进本仓库、代码或工具参数。

无论选哪种方式，都要确认：

opencode --version

能正常运行，并且 OpenCode 已在其自己的配置中完成模型/API 配置。

首次使用时：

1. 调用 opencode.configure，不传参数。

2. 从返回的模型列表中选择一个已按 550k 配置的 <provider-id>/<model-id>。

3. 再次调用 opencode.configure，将它作为 defaultModel。

4. 使用 opencode.run 向 OpenCode 发送简短工作指令。

日常使用时，Codex 可先调用 opencode.sessions 查看近期会话，再用 opencode.run 复用会话或启动新工作。需要并行时，传入 backgroundSubagents: true；它只会启用 OpenCode 原生后台子代理。

工具参考

会话和权限

本地注册表按工作目录隔离，只保存会话 ID、父会话 ID、模型 ID、时间戳及活动任务 ID。它不保存提示词、代码、Diff、日志、模型输出、路径、密钥或项目摘要。OpenCode 才是会话历史与输出的唯一来源。

标准 MCP 无法把 Codex Desktop 的实时逐命令审批状态传给服务器，因此无法承诺完全相同的动态权限。桥接器采取更严格的下限：edit、bash、webfetch、external_directory 和 doom_loop 均为 ask。当 OpenCode 请求操作许可时，用 opencode.sessions 查看并显式响应。

开发

npm test
npm run build
npm pack --dry-run

Related MCP server: opencode-chatgpt-bridge

English

What it is for

codex-mcp-opencode makes Codex Desktop the planner and dispatcher for a project, while OpenCode is the execution agent. Codex sends short, specific work instructions; OpenCode reads code, configuration, and existing context directly from the project directory in which it was launched.

This is not a second project-memory system or an API-key manager. It never sends source trees or broad project summaries back through the bridge. Providers, models, and credentials remain entirely in OpenCode.

Key capabilities

Prerequisites

1. Node.js 20 or later.

2. opencode installed on PATH, with models and credentials configured in OpenCode.

3. The target OpenCode model configured with limit.context set to 550000.

4. Native OpenCode compaction enabled: compaction.auto: true and compaction.prune: true.

Before execution, the bridge checks the model's reported limit.context and refuses anything other than 550000. This keeps DeepSeek below the chosen compaction boundary rather than allowing it to reach roughly 600k first. The setting belongs in OpenCode configuration; the MCP never rewrites providers, models, or API keys.

Use this portable OpenCode configuration shape, replacing the placeholders with your provider and model IDs:

{
  "provider": {
    "<provider-id>": {
      "models": {
        "<model-id>": {
          "limit": { "context": 550000, "output": 32000 }
        }
      }
    }
  },
  "compaction": { "auto": true, "prune": true }
}

Installation and connection for other users

This repository can currently be installed directly from GitHub; it has not been published to npm. Users do not need to edit source code, enter API keys, or provide project paths in tool calls.

Option 1: use GitHub directly in Codex MCP configuration (recommended)

Configure this command as a Codex stdio MCP server:

command: npx
args:    --yes github:Ichikawashadow/codex-mcp-opencode

Codex must start the command from the currently opened target project directory. When npx obtains the package from GitHub it runs prepare to build it; the MCP still starts OpenCode inside the current project.

Option 2: clone and install locally

git clone https://github.com/Ichikawashadow/codex-mcp-opencode.git
cd codex-mcp-opencode
npm ci
npm run build

Then configure this program as a Codex stdio MCP server:

command: node
args:    <installation-directory>/dist/index.js

<installation-directory> is the user's local MCP installation, not the target project path. It belongs only in the user's Codex configuration, never in this repository, source code, or tool arguments.

With either option, confirm that:

opencode --version

works and that OpenCode has its own model/API configuration.

First use:

1. Call opencode.configure with no arguments.

2. Select an OpenCode model already capped at 550k from the returned list.

3. Call opencode.configure again with that <provider-id>/<model-id> as defaultModel.

4. Use opencode.run to send short work instructions to OpenCode.

For daily work, Codex can call opencode.sessions to inspect recent sessions and then call opencode.run to reuse a session or start fresh work. For parallel work, pass backgroundSubagents: true; this only enables OpenCode native background subagents.

Tool reference

Sessions and permissions

The small local registry is isolated by launch directory. It stores only session IDs, parent session IDs, model IDs, timestamps, and active task IDs. It never stores prompts, code, diffs, logs, model output, paths, keys, or project summaries. OpenCode is the single source of truth for session history and output.

Standard MCP does not expose Codex Desktop's live per-command approval state to servers, so exact dynamic permission mirroring is impossible. The bridge takes the stricter floor: edit, bash, webfetch, external_directory, and doom_loop all start as ask. Use opencode.sessions to inspect and explicitly answer OpenCode permission requests.

Development

npm test
npm run build
npm pack --dry-run