프로토타입 · 미리 보기: 공식 레지스트리의 모든 서버를 담고 있으며 30분마다 동기화해요. 리뷰와 계정 기능은 다음 단계에서 열려요.
PopNx MCPAI를 쓰는 사람을 위한 MCP 서버 · 쉬운 말로 설명해요

Codex Supervisor MCP

제작자: zriyox버전 0.8.0i★ –i내 컴퓨터에서 실행
레지스트리 이름io.github.zriyox/codex-supervisor-mcp

설치

개요

제작자가 쓴 설명(영어 원문)

Parallel Codex CLI workers from any MCP client: one git worktree each, state in SQLite, web board.

PopNx MCP의 세 기둥

이 세 가지는 절대 하나의 점수로 합치지 않아요. 의견, 측정, 인기는 서로 다른 것이니까요.

할 수 있는 일

이 서버는 아직 쉬운 말로 된 요약을 쓰지 못했어요. 아래는 레지스트리에서 읽어 온 사실이에요.

  • 연결 방식: 내 컴퓨터에서 실행
  • 전송 방식: stdio
  • 카테고리: 데이터베이스 및 데이터셋

설치

쓰고 있는 AI 앱을 고른 다음 설정을 복사하세요.

설치하기 전에

  • 기본 점검: 1개 중 1개 통과
  • 내 컴퓨터에서 내 사용자 계정의 권한(파일, 네트워크, 앱)으로 실행돼요.
  • 직접 입력할 값: CODEX_BIN, SUPERVISOR_HOME

필요한 것

  • npmNode.js 설치(npx 명령어용)

어떤 앱을 쓰세요?

위에서 앱을 고르세요. 기억해 두었다가 다음부터는 버튼에 “…에 설치”라고 표시해요.

Claude Desktop → Settings → Developer → Edit Config를 열고 claude_desktop_config.json에 이 내용을 붙여 넣으세요

{
  "mcpServers": {
    "codex-supervisor": {
      "command": "npx",
      "args": [
        "-y",
        "codex-supervisor-mcp"
      ],
      "env": {
        "CODEX_BIN": "your-value",
        "SUPERVISOR_HOME": "your-value"
      }
    }
  }
}

터미널에서 이 명령어를 실행하세요

claude mcp add codex-supervisor --env CODEX_BIN=your-value --env SUPERVISOR_HOME=your-value -- npx -y codex-supervisor-mcp

실행하기 전에 빈 값을 채워 주세요.

Cursor에서 열기

또는 설정을 직접 복사하기

프로젝트의 .cursor/mcp.json 또는 ~/.cursor/mcp.json에 붙여 넣으세요

{
  "mcpServers": {
    "codex-supervisor": {
      "command": "npx",
      "args": [
        "-y",
        "codex-supervisor-mcp"
      ],
      "env": {
        "CODEX_BIN": "your-value",
        "SUPERVISOR_HOME": "your-value"
      }
    }
  }
}

브라우저가 앱을 열지 물어본 다음, 앱이 설정을 보여 주고 확인을 요청해요. 키 값은 비워 두니 직접 입력하세요.

VS Code에서 열기

또는 설정을 직접 복사하기

프로젝트의 .vscode/mcp.json에 붙여 넣으세요

{
  "servers": {
    "codex-supervisor": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "codex-supervisor-mcp"
      ],
      "env": {
        "CODEX_BIN": "your-value",
        "SUPERVISOR_HOME": "your-value"
      }
    }
  }
}

브라우저가 앱을 열지 물어본 다음, 앱이 설정을 보여 주고 확인을 요청해요. 키 값은 비워 두니 직접 입력하세요.

이 서버는 내 컴퓨터에서 실행되는데, ChatGPT는 인터넷에 있는 서버에만 연결할 수 있어요. 다른 앱을 고르세요.

선택한 앱은 이 기기의 쿠키에만 저장돼요. 계정은 필요 없어요.

직접 입력할 값

  • CODEX_BIN env
    Path to the codex CLI when it is not on PATH
  • SUPERVISOR_HOME env
    State directory, default ~/.codex-supervisor

이 설정은 제작자의 레지스트리 정보로 만들었어요. README와 다르면 README를 따르세요.

할 수 있는 일

내 컴퓨터에서 실행돼요. 설치하면 AI 앱에 도구 목록이 나타나요.

기본 점검i

누구나 볼 수 있는 정보를 점검했고, 코드는 읽지 않았어요. 해당하지 않는 항목은 개수에서 뺐어요. · 2026년 11월 7일 점검

  • ✓ 통과

    제작자와 저장소 일치

    레지스트리 이름이 GitHub 계정 zriyox 기준으로 확인되었고, 이 계정이 저장소를 소유하고 있어요

  • … 아직 점검 안 함

    계속 관리되고 있음

    아직 GitHub에서 이 저장소를 읽어 오지 않았어요

  • … 아직 점검 안 함

    라이선스 있음

    아직 GitHub에서 이 저장소를 읽어 오지 않았어요

  • – 해당 없음

    엔드포인트 응답

    내 컴퓨터에서 실행되는 서버라 인터넷 엔드포인트가 없어요

  • – 해당 없음

    OAuth로 로그인

    내 컴퓨터에서 실행되며, 대신 로컬 설정을 사용해요

  • … 아직 점검 안 함

    도구 설명에 숨겨진 지시 없음

    내 컴퓨터에서 실행돼요. 도구 목록은 인터넷 엔드포인트가 있는 서버에서만 읽을 수 있어요

데이터베이스 및 데이터셋 카테고리의 다른 서버와 비교i

  • 이 카테고리의 다른 서버 952개 중 0%보다 스타가 많아요
  • 이 카테고리의 다른 서버 952개 중 66%보다 최근에 레지스트리에 공개됐어요
  • 기본 점검 결과가 이 카테고리의 다른 서버 952개 중 100%와 같거나 더 좋아요

레지스트리에서 이 카테고리의 활성 서버 전체와 비교했어요. 스타는 게시자가 저장소를 소유한 경우에만 세요.

자주 묻는 질문

Codex Supervisor MCP, 안전한가요?

해당하는 기본 점검 1개 중 1개를 통과했어요. 코드는 읽지 않았어요. 키나 토큰을 넣기 전에 서버가 어떤 권한을 요구하는지 확인하고, 꼭 필요한 권한만 있는 키를 쓰세요.

어떤 키나 코드가 필요한가요?

레지스트리에 필수 키가 나와 있지 않아요. 다만 처음 쓸 때 로그인을 요구하는 서버도 있어요.

내 컴퓨터에서 실행되나요, 클라우드에서 실행되나요?

내 컴퓨터에서 실행돼요. AI 앱이 필요할 때 실행하고, 데이터는 제작자의 서버를 거치지 않아요(서버 자체가 온라인 서비스를 호출하는 경우는 제외).

아직 관리되고 있나요?

GitHub 저장소는 마지막으로 – 변경됐고, 최신 버전(0.8.0)은 29일 전 레지스트리에 올라왔어요.

어떤 앱에서 쓸 수 있나요?

Claude Desktop, Claude Code, Cursor, VS Code처럼 MCP를 지원하는 앱에서 쓸 수 있어요. 내 컴퓨터에 Node.js도 있어야 해요.

대신 쓸 수 있는 건 뭐가 있나요?

같은 카테고리에는: Supabase, MongoDB MCP Server, Elasticsearch MCP Server

대안

같은 카테고리에서 다른 제작자가 만든 서버예요. 스타 순으로 정렬했어요.

카드 보는 법:★ GitHub 스타i세 기둥: 리뷰 · 점검 · 사용 정도i업데이트 = 최신 버전을 레지스트리에 공개한 날i

Supabase

제작자: supabase

MCP server for interacting with the Supabase platform

컴퓨터 또는 클라우드★ 2,993Apache-2.0오늘 업데이트
설치

MongoDB MCP Server

제작자: mongodb-js

MongoDB Model Context Protocol Server

내 컴퓨터에서 실행★ 1,157Apache-2.0그저께 업데이트
설치

Elasticsearch MCP Server

제작자: cr7258

MCP server for interacting with Elasticsearch

내 컴퓨터에서 실행★ 315Apache-2.014개월 전 업데이트
설치

제작자의 README

README 열기

제작자의 저장소에서 쓰인 그대로 가져왔어요. PopNx MCP가 검토하거나 보증한 내용이 아니에요. HTML, 이미지, 스크립트는 제거했어요. 링크를 누르면 이 사이트를 벗어나요.

codex-supervisor-mcp

English | 中文

官网 codex-supervisor.zriyo.com · 给模型读的 llms.txt

让几个 agent 同时改一个仓库,结果是互相覆盖、没人说得清谁改了什么,主线程的上下文还被 worker 的输出塞满。

codex-supervisor-mcp 是一个 Codex MCP server,把「派单」和「记账」从模型上下文里拿出来放到磁盘上:一个主线程(Claude Code、Codex 或任何 MCP 客户端)同时指挥多个 Codex CLI worker,一个 worker 一个 Git worktree,状态落盘到 SQLite,附一个网页看板。

*30 秒真跑:create_codex_worker ×3,三个 worker 各自 worktree 并行,主线程收 3 份 diff 合成一次 commit。*

解决什么

问题做法
几个 worker 互相踩文件一个 worker 一个 Git worktree,ownedPaths 在派单前查冲突
worker 不是只会改代码四种 workspaceKind:Git 编辑 git_worktree、只读 read_only_in_place、联网研究 scratch、显式授权的非 Git 写入 in_place_write;非 Git 默认绝不写原目录
worker 的过程塞爆主线程上下文事件写 data/runs/ .jsonl,读的时候有 limit / maxChars / kinds 三道闸
主线程读一次状态就顶满get_orchestration_overview 把全部 worker 压进 7000 字节
进程重启后不知道谁还在跑supervisor.sqlite 一行一个 work,带 thread_id
换个会话接不上之前的 workerresume_codex_worker 走 codex exec resume ,接的是同一个 Codex 会话
分不清「跑失败」和「进程没了」状态机把 failed 和 lost 分开
分不清是谁报错status / overview / overview_delta 带 failure.source 和 failure.code,区分 provider、supervisor_process、workspace_setup、model_output、acceptance、worker_process
worker 说做完了其实没有派单给 acceptance 验收命令,worker 退出后 supervisor 在它的 worktree 里跑,失败 land 拒绝
看不见一批活现在到哪了codex-supervisor-web 开一个看板,按 session 看每路 worker 在干什么
改动留在本地没上线收活默认 land_codex_worker 合回主分支;主线程自己的改动必须 commit + push;部署前用远端 SHA 核对文件真的在线上
worktree / 分支越堆越多verify_delivery_push 后自动生成 cleanup plan;只对 acceptance passed + push_verified + clean 判 SAFE,主线程显式 apply_cleanup 才删 worktree,branch/证据永远保留

worker 跑的是 codex exec,model 透传:主线程留在 Claude,worker 可以挂 DeepSeek 或任何 Codex 配了 provider 的模型,账单分开算。

五分钟跑起来

前置:Node.js 22.13.0 以上,codex CLI 在 PATH 里。macOS、Linux、Windows 都行。

1. 装
npm install -g codex-supervisor-mcp

npm 全局安装在允许执行安装脚本时,会运行 postinstall,给检测到的 Claude Code/Codex 装 skill 并注册 MCP。--ignore-scripts、禁用安装脚本或只运行 npx 不保证自动注册;没看到时先运行 codex-supervisor-setup,再查两端 mcp get。手动注册也可以:

claude mcp add -s user codex-supervisor -- npx -y codex-supervisor-mcp

codex mcp add codex-supervisor -- npx -y codex-supervisor-mcp

重启 Claude Code / Codex。以后不用再手动更,见「更新」。只要 skill 不要 MCP:npx skills add zriyox/codex-supervisor-mcp。

2. 派第一批活

在 Claude Code 里直接说人话,skill 会让它走正确的流程:

把这三个模块的单测补齐,用 codex-supervisor 分三路并行跑,session 叫「补单测」。

主线程背后做的事(你也可以自己调工具):

preflight_codex_worker  同 workspace/base/sandbox/guard 先跑必要 probe

get_worker_preflight 确认 passed;contract 变化就重跑 create_codex_worker ×3 每路带 preflight_id、session_id、ownedPaths、goal wait_codex_workers 默认等 60 秒,到点返回快照,没完就接着等 get_worker_result ×3 收每路的汇报,带它真跑过的命令和退出码 get_worker_diff ×3 看实际改动;证据对得上再决定是否 land

每路的改动在各自的 codex/ 分支上。验收和 diff 都过了,主线程用 land_codex_worker 带 commitMessage 合入;worker 不自行提交。

3. 开看板
codex-supervisor-web

没全局装也能起:

npx -p codex-supervisor-mcp codex-supervisor-web

打开 http://127.0.0.1:7877。状态目录按 SUPERVISOR_HOME、最近的 .mcp.json、~/.codex-supervisor 的顺序找;端口用 SUPERVISOR_WEB_PORT 改。看板只看,不派单不取消。

长门禁脚本可主动上报阶段:

node "$CODEX_SUPERVISOR_STAGE_CLI" "gate:s3" --detail "integration queue"

current_stage 会出现在 status / overview / wait,终态保留为 last_stage;不要放 token、密码或 DSN。

我自己怎么用

能连 MCP 的都能当主线程,这里只是我的用法。我开两个 Claude Code 会话,一个只管文档,一个只管派活:一个会话又写详设又盯 worker,上下文两小时就满。

谁开在哪管什么
我定需求,拍板,看汇报
规划会话需求和文档仓聊需求,写详设,每一块活写一份任务书,末尾附一段发给主脑的话
主脑会话代码仓的一个 worktree读任务书,派 Codex worker,核每路的 diff,把结果填回任务书,向我汇报。不写业务代码
Codex worker各自的 worktree一个 worker 做一个能独立验收的功能包,在远端机器上修改、运行验收。不 commit、不 push、不合并

两个会话之间只传一段文字,粘进主脑会话用 /goal 接上。结构固定:

【角色】   你是主脑:读文档和代码,派 worker,核结果,更新文档,向我汇报。不写业务代码。

派活和盯进度用 codex-supervisor 这个 skill,开工前先加载它。 【背景】 这一块为什么做,上一块留下了什么 【先读】 哪几份文档的哪几节。几份说法不一样时以哪份为准 【仓和分支】工作目录在哪,各分支现在在哪个提交,哪些分支只读 【做什么】 照任务书第几节那张表做。按能独立验收的功能包拆,表里没有的不做。worker 不自行 commit 【派活】 先 search_works 看有没有派过,别重复 整批用同一个 session_id 改同一批文件就串行,写入范围不重叠才并行。ownedPaths 覆盖实现、测试、路由、DI、配置和迁移 依赖先写 workspaceSetup;写 worker 先过同 contract 的 preflight task 写全:背景、文档出处、完整写集、验证命令、输出格式 验证命令同时填 acceptance;worker 用 CODEX_SUPERVISOR_ACCEPTANCE_CLI 自查 worker 交回来先看 diff。它说过了不算,你看到才算 【构建和测试】全走远端机器,本机不跑 【红线】 不改什么,不推什么,不读什么 【必须停下来问我】 【汇报】 中文,表格优先,报哪几项,然后停下来等我

主脑一轮下来调的工具:

search_works            查这批活派过没有

preflight_codex_worker 同环境跑 probe,确认 sandbox / guard / base / cache 真可用 get_worker_preflight 核 probe 的实际 command evidence;passed 才能派目标 worker create_codex_worker 一个功能包一个 worker,同一个 session_id,ownedPaths 不重叠 wait_codex_workers 60 秒一轮,compact: true,没完接着调 get_worker_result 它说自己做了什么,verification 里是它真跑过的命令 get_worker_diff 它实际做了什么 ask_codex_worker 对不上就问它为什么,只读,不动它的线程 resume_codex_worker 要改就继续同一线程;主线走远了带 rebaseOnto land_codex_worker 核过了,带 commitMessage 代提交并落进集成分支

功能包在 land 前仍可 resume_codex_worker 继续修改。真正需要拆开的原因是写集冲突、依赖顺序或独立验收,不是“每一步都必须换一个模型线程”。

看板里有什么

位置内容
左栏每个 session 一行:标题、worker 数、几路在跑、最近活动。左下角是版本和更新提示
session 页统计(总数 / 运行中 / 完成 / 失败 / 丢失),有 worker 在跑时列每路正在执行的命令
worker 台账一行一路:状态、标题、正在跑的命令或最后一句汇报、耗时、改了几个文件、跑了几条命令
worker 抽屉七个 tab:概览、汇报、改动、命令、事件、任务书、旁问
旁问对这路 worker 提问,就是 Codex 的 /btw:从它的线程 fork 出只读旁路会话来答,不碰它正在跑的活。多轮、可中断、换标签页回来自动接上

浅色深色跟系统走,没有外网资源。

工具

39 个。

工具入参作用
check_workers无参返回新终态、故障及长线程交接提醒;同一 run 的 handoff 只提醒一次,不中止或复制活跃 worker。已死的第1轮 lost / no_work / invalid_report 最多恢复一次;用宿主定时调用及独立 CODEX_SUPERVISOR_OBSERVER_ID 接回
overview_deltacursor主线程默认轮询入口:只返回 active / needs_attention / ready_to_land / ready_to_clean、cursor 后变化、短版 attention_reason / next_action 和 next_cursor;不返回全量历史、prompt、diff、event 或 worker capsule
check_acceptancecwd, acceptance, baseRef, timeoutMs派单前实际运行给定验收命令,不建 worker,不证明 worker 完成;数量 grep 会提示不能证明失败名单和必跑执行
preflight_codex_workercwd, workspaceKind, inPlaceAuthorization, workspaceSetup, ownedPaths, probeCommands, baseRef, sandbox, allowedCommands, context, contracts, networkAccess, writableRoots用与目标 worker 相同的 workspace/base/sandbox/guard 起短 probe worker;它必须实际跑完每条 probe command。probe 自动获得本次 guard-only 允许,但不进入目标 worker contract;联网和凭据目录仍须显式授权
get_worker_preflighttask_id返回 probe 的实际 command evidence、运行环境 contract hash、worker outcome 和 running/passed/failed;probe 全部执行通过时,报告 JSON 错误或已 exit 0 的 close-handler 缺失只留诊断,不误判环境失败
create_codex_workertask, cwd, workspaceKind, inPlaceAuthorization, workspaceSetup, `ownedPaths`, `goal`, preflight_id, forbid, allowedCommands, context, contracts, externalOutputs, networkAccess, writableRoots, maxRunMs, maxTotalMs, acceptance, session_id, session_title, session_note, dependsOn, baseRef, sandbox, model, reasoningEffort, title, skipGitRepoCheckGit 默认隔离 worktree;非 Git 写入必须选 scratch 或有授权、paths、acceptance 的 in_place_write。workspaceSetup 在起 worker 前链接依赖、初始化子模块、跑 prepare;preflight_id 给了就必须是通过的同环境 probe
create_codex_followup_workertask_id, followup_prompt, session_id, session_title, title, cwd, sandbox, model, ownedPaths, forbid, allowedCommands, context, contracts, externalOutputs, networkAccess, writableRoots, workspaceKind, workspaceSetup, goal, baseRef, acceptance新会话继承父任务上下文:未 land 用父分支当前提交,已 land 用当前集成 HEAD,显式 baseRef 优先。未提交父改动不复制;不支持 preflight_id、dependsOn、skipGitRepoCheck
resume_codex_workertask_id, prompt, rebaseOnto, acceptance, context接同一个 Codex 会话继续跑,thread_id 不变。原生 goal 仍 active 或 goal 状态库不可判定时,本轮自动省略 output schema,避免 ActiveTurnOutputSchemaMismatch。rebaseOnto 先把 worktree 挪到主线新头(stash、跳过已合入补丁、重放新增提交、放回),冲突原样退回不起 worker
wait_codex_workerstask_ids, mode(any/all), timeoutMinutes, timeoutMs, allowLongWait, compact, emitProgress, includeEvents, eventLimit, eventMaxChars, eventKinds等终态,单次预算默认最多 60 秒,只有确认宿主超时允许后才传 allowLongWait: true。返回实际/请求预算与 timeout_capped,termination_reason 区分 settled / budget_exhausted / client_cancelled;emitProgress 可选,每路摘要用 compact
get_orchestration_overviewstatus, limit全部 worker 的状态表,封顶 7000 字节。带 version 和 update
get_worker_resulttask_id, limit, maxChars, includeFilesworker 自己的汇报,默认截 6000 字节、truncated 提示读全。acceptance 是 supervisor 替你跑的验收过没过,verification 是它自己跑过的命令和退出码,base_behind 是主线走了多远(contains_base: false 时 behind 为 null,那是换了线)
get_worker_difftask_id, file, hunk, pageSize, cursor, maxChars, pathsworker 实际改了什么。默认完整文件索引与 hunk 数;按 file + hunk/cursor 分页读 patch。显式 maxChars 且不传 file 保留旧整份限流模式
ask_codex_workertask_id, question, timeoutMs, maxChars, fresh, end旁路问 worker 一句。线程 fork 成只读侧会话,没网络、没 MCP 工具,worker 本身不动。worker 被 resume 过会自动换新 fork,fresh 强制换,end 删
land_codex_workertask_id, onto, commitMessage, includeFollowupParents, commitMessages, ignoreAcceptance, allowOutsideOwned把 worker 在 codex/ 上的提交 cherry-pick 到派单目录的当前分支。目标要干净,冲突回滚,验收 failed 拒绝;报告格式错不再单独阻止显式 land。commitMessage 先替当前 worker 把未提交改动提交成一笔;includeFollowupParents 按 root-first 落地整条 followup 链,commitMessages 给链中各路提供各自的 checkpoint 提交说明
verify_delivery_pushtask_id, remote, branchfetch 指定 remote branch 并证明 landed_head 已可达;只读验证,不会 push 或部署。通过后记录 push_verified 并生成 cleanup plan
cleanup_plantask_ids, project_root生成 15 分钟有效的 SAFE / REVIEW / BLOCKED 计划,含原因、fingerprint 与回收空间估算;SAFE 必须 acceptance passed、push verified、干净且无活跃依赖/进程
apply_cleanupplan_id, item_ids只在未过期计划上二次校验 SAFE item、重新 fetch remote 并确认 landed SHA 仍可达后执行 git worktree remove/prune;保留 branch、task、events、JSONL、artifacts
cleanup_historytask_id, limit查询 cleanup 的计划、理由、fingerprint 和实际回收记录
get_worker_summarytask_id一段话:goal、状态、改动、最后一条命令和消息
get_codex_worker_statustask_id, includePrompt, promptMaxChars单个 worker 的状态细节
get_codex_worker_eventstask_id, limit, maxChars, kinds原始事件流
get_context_snapshot_metatask_id只读 worker context 的 snapshot ID、fact IDs、token 估算和排除项;不返回 capsule 正文或历史记录
get_factfact_id按 ID 审计原始 fact 版本及 effective_state;撤销和自动过期均保留原版本
search_worker_factstask_id, query, limit, cursor只检索当前 work、显式依赖和路径命中 repo scope 的 verified facts;返回 coverage / next_cursor,不返回 raw history
get_worker_evidencetask_id, limit返回某 worker 的有界 event 元数据和 retained artifact 索引;按需再点查 artifact / event
get_artifactartifact_id, maxChars读取一个 supervisor-managed evidence artifact;不影响 worker capsule 或主线程自动上下文
promote_worker_factfact_id, scope, watchedPaths, expiresAt主线程显式把 candidate 追加为 verified fact;repo scope 必须声明 watchedPaths,worker 不能自升真相
revoke_worker_factfact_id, reason主线程审计后追加撤销版本和事件,不覆盖原 fact;被撤销事实从 search / capsule 排除

| create_independent_verifier | task_id, title | 为已结算 worker 创建独立 read-only / 无网络 verifier;只给

앞부분만 보여 드려요. 나머지는 저장소에서 읽어 보세요

PopNx에게 묻기