Skip to main content
Glama

Codex MCP

English | 简体中文

Let Claude Code (or another compatible MCP client) hand coding work to your local OpenAI Codex CLI, and keep a two-way conversation with it.

Codex MCP is a small local MCP server. It turns the Codex CLI on your computer into a persistent coding subagent for your main AI agent:

  • Persistent conversations. Start a task, send follow-ups, steer or interrupt it, and resume it after a restart.

  • Two-way communication. Codex can ask the main agent questions (ask_parent), and the main agent answers them.

  • Safe approvals. Nothing is approved silently. Approvals go to you, or to Codex's own automatic reviewer if you choose Approve for me.

  • Project-scoped sandbox. Codex's commands can change files only in the task's project folder, and they have no network access unless you approve it. Outside the project they can read only what programs need to run. See security.

  • Native Codex features. Subagents, plan mode, code review, forks, queues, history and more: 34 tools in total.

  • Parallel work and limits. Optional Git worktrees give parallel tasks their own checkout and hand back a reviewable patch; small plans start dependent steps in order; family budgets cap turns, time, tokens and stored output.

  • No extra dependencies. Uses only the Python standard library. Works on Windows, macOS and Linux, using local pipes and sockets only (never a network port).

Contents

Related MCP server: Codex MCP Server

Requirements

You need

Version

Check with

Python

3.11 or newer

python3 --version (Windows: py -3 --version)

OpenAI Codex CLI

0.167.0 or newer

codex --version

A Codex sign-in

ChatGPT account or API key

codex login status

An MCP client

Claude Code, Claude Desktop, or another stdio client

Codex's own sandbox must work on your computer. The bridge never turns it off. On Windows, Codex's legacy unelevated sandbox is not supported; use the sandbox mode Codex sets up by default (see installation details).

Installation

The steps below use Claude Code. For other clients, see Step 5 and docs/installation.md.

Step 1: Install Python

  • Windows: Install Python 3.11+ from python.org. In the installer, tick Add python.exe to PATH. This also installs the py launcher used below.

  • macOS: brew install python, or use the installer from python.org.

  • Linux: Use your distribution's package, for example sudo apt install python3.

Step 2: Install and sign in to Codex

npm install -g @openai/codex
codex login

Any official installation method works. See OpenAI's Codex CLI guide. Then check:

codex --version
codex login status

The version must be 0.167.0 or newer. Run codex update to upgrade an older installation.

Step 3: Download Codex MCP

Get the code from the codex-mcp repository and keep the folder in a permanent location (for example ~/tools/codex-mcp or C:\Tools\codex-mcp), because your MCP client runs the server from there. The repository is public, so you don't need a GitHub account.

  • Git:

    git clone https://github.com/houyhlouis/codex-mcp.git
    cd codex-mcp
  • GitHub Desktop: Choose File → Clone repository, open the URL tab, enter https://github.com/houyhlouis/codex-mcp, choose a local path, and click Clone.

  • ZIP: On the latest release page, download Source code (zip) and extract it. Rename the extracted folder to codex-mcp.

Nothing needs to be installed after downloading: the server runs straight from this folder. If you would rather have a codex-local-mcp command, see installing as a Python package.

Step 4: Check that it works

Run these commands in the codex-mcp folder.

macOS / Linux:

python3 server.py --version
python3 server.py status

Windows (PowerShell):

py -3 server.py --version
py -3 server.py status

status starts the background broker and Codex, then prints JSON that should include "signed_in": true. It does not run a model or use any quota. The broker keeps running in the background and is started again automatically when it is needed.

Step 5: Connect your MCP client

Claude Code. Run this inside the codex-mcp folder.

macOS / Linux:

claude mcp add --transport stdio --scope user codex -- python3 "$PWD/server.py" serve

Windows (PowerShell):

claude mcp add --transport stdio --scope user codex -- py -3 "$PWD\server.py" serve

--scope user makes the server available in all your projects. Leave it out to add it to the current project only. Check the connection with claude mcp list, or type /mcp inside Claude Code. codex should show as connected.

Claude Desktop and other clients. Add this to the client's MCP configuration file (for Claude Desktop: Settings → Developer → Edit Config), then restart the client:

{
  "mcpServers": {
    "codex": {
      "command": "python3",
      "args": ["/absolute/path/to/codex-mcp/server.py", "serve"]
    }
  }
}

On Windows use "command": "py" and "args": ["-3", "C:\\Tools\\codex-mcp\\server.py", "serve"]. Ready-made files: examples/mcp.json and examples/mcp.windows.json.

Step 6 (optional): Teach your agent the workflow

Copy examples/CLAUDE.md into your project's CLAUDE.md (or your agent's instructions file). It explains how to poll for progress, answer questions and treat approvals.

No configuration file is needed. Optional settings, such as a custom Codex path or concurrency limit, are described in docs/configuration.md.

Your first task

Ask your main agent in plain language:

Use Codex in this project to find out why the tests fail and fix them.
Keep me updated and answer any questions it asks.
Create a new project folder ~/projects/todo-cli and ask Codex to build a small
command-line to-do app with tests. Use "Approve for me" for this task.
Continue the same Codex conversation: add a --json flag and run the tests again.

Behind the scenes, the main agent selects a project with codex_projects, starts work with codex_start, and polls codex_events until the turn finishes. It answers Codex's questions with codex_respond and reads the result with codex_get. See the usage guide for the full workflow and more examples.

Approvals

Codex asks for approval before actions outside its sandbox, such as running a command that needs network access. You choose who decides for each task with approval_mode:

Mode

Who decides

inherit (default)

Whatever your Codex configuration already uses

ask

You. The request is shown as a prompt in your MCP client, or you review it in a terminal

approve_for_me

Codex's built-in automatic reviewer. It can approve or deny; the sandbox stays on

The main agent can always deny a request, but it cannot approve one on your behalf unless you explicitly enable approval_relay in the configuration. If your client cannot show prompts, review the request in a terminal:

python3 server.py review REQUEST_ID

Updating and uninstalling

Update:

cd codex-mcp
python3 server.py stop
git pull

Then restart your MCP client. (Windows: py -3 server.py stop.) Always stop the broker before you update, so that the old broker never loads a file from the new version. Otherwise the client also reports that a broker from a different version is still running. Stop it when no task is working: a task that is interrupted by the stop keeps its project reserved until you call codex_resume for it.

If you installed from a ZIP, run python3 server.py stop first, then replace the folder with the new Source code (zip) from Releases.

Uninstall:

  1. python3 server.py stop

  2. claude mcp remove codex --scope user (or remove the entry from your client's configuration)

  3. Delete the codex-mcp folder.

  4. Optionally delete the saved task history: ~/.local/state/codex-mcp on macOS/Linux, %LOCALAPPDATA%\CodexMCP on Windows.

Troubleshooting

Problem

What to do

Anything unclear

Run python3 server.py doctor. It checks the installation without starting anything or using a model, and suggests a next step for each problem. See troubleshooting.

Codex executable not found

Make sure codex --version works in a new terminal, or set codex_binary to its full path in a config file.

codex does not appear in /mcp

Check the path in your client's configuration and run the same command by hand, for example python3 /path/to/server.py status.

A broker from a different version or configuration is running

Run python3 server.py stop (with the same --config if you use one), then retry.

A task is stuck in waiting

It is waiting for an answer or approval. Ask the main agent to list pending requests, or run server.py review REQUEST_ID.

Something else

See docs/troubleshooting.md. The private log is broker.log in the state folder.

How it works

flowchart LR
    A[Main agent<br/>e.g. Claude Code] <-->|MCP over stdio| B[server.py serve]
    B <-->|private local socket / pipe| C[Background broker]
    C <-->|app-server protocol| D[Codex CLI]
    D --> E[Your project]

The MCP server that your client starts is a thin adapter. A background broker owns the Codex connection, stores tasks and events in a private SQLite database, and keeps running when the client disconnects. A reconnecting client can catch up from where it left off. See architecture and security.

The sandbox applies to the commands Codex runs, not to Codex itself: the Codex process still uses your sign-in and the network to reach the model. Security lists exactly what commands can read and change.

Documentation

Guide

What it covers

Installation details

Other MCP clients, package install, Windows notes, running the broker manually

Usage guide

The task workflow, approvals, subagents, plan mode, forks, queues, recovery

Tool reference

All 34 tools, their arguments, task states and response formats

Configuration

Optional settings file

Troubleshooting

Common errors and how to fix them

Security

Trust model, sandbox, approvals and stored data

Architecture

Components, message flow and delivery guarantees

Limitations

What is intentionally not supported, and workarounds

Development

Tests, CI, live checks and release packaging

Changelog

Release notes

Development

python3 -m unittest discover -v

The offline suite uses a simulated Codex process and uses no model quota. CI runs it on Windows, macOS and Linux with Python 3.11 and 3.14 after every push. See docs/development.md and CONTRIBUTING.md.

License

MIT

Available Tools

34 tools
codex_archiveA
Destructive

Archive or restore an idle conversation and its native descendants. Transcripts are retained.

Inputs: task_id (required), action, request_id, operation_id. Returns: ok, result_version

codex_capabilitiesC
Read-onlyIdempotent

Discover native collaboration/permission options and direct-input capability for a task.

Inputs: task_id (required). Returns: ok, result_version

codex_compactA
Destructive

Request native history compaction for an idle conversation; may consume model usage. Poll completion events.

Inputs: task_id (required), request_id, operation_id. Returns: ok, result_version

codex_delegateB
Destructive

Ask a parent to manage native subagents; discover them with codex_subagents. Active parents require expected_turn_id.

Inputs: prompt (required), task_id (required), contract, request_id, +2 more. Returns: ok, result_version

codex_deleteA
Destructive

Permanently delete an owned native conversation and descendants. Requires the exact native thread_id in confirm_thread_id and an idle family. Local bridge audit records remain.

Inputs: task_id (required), confirm_thread_id (required), request_id, operation_id. Returns: ok, result_version

codex_diffA
Read-onlyIdempotent

Retrieve the current native turn's diff and reported file changes; old diffs are not carried into new turns. Does not invoke Git hooks or execute a shell.

Inputs: task_id (required). Returns: ok, result_version

codex_eventsB
Read-onlyIdempotent

Replay progress or wait up to 25s. Drain has_more. For fragments, keep after and use event_seq/next_event_offset until complete. Page requests with requests_cursor. outcome coalesces state for task_ids (max 50); return cursors unchanged on the next poll. Detailed replay uses after separately.

Inputs: view, after, limit, cursors, +9 more. Returns: ok, result_version

codex_forkA
Destructive

Fork an idle owned conversation, optionally through a selected turn. Keeps project boundaries; does not start work or automatically continue a goal.

Inputs: task_id (required), name, request_id, last_turn_id, +1 more. Returns: ok, result_version

codex_getC
Read-onlyIdempotent

Read task state and cumulative usage. workspace_claims explain ownership; page requests, children and claims. Large fields identify truncated_fields. result pages turn evidence (pin result_id); artifact reads scoped bytes by artifact_id. Use offset/limit. reconciliation explains recovery; permissions pages receipts and scope.

Inputs: task_id (required), view, limit, offset, +9 more. Returns: ok, result_version

codex_goalA
Destructive

get reads a goal; set takes objective/status/token_budget; clear removes it. Mutations need user_requested=true and an operation key. Only change goals on explicit human instruction.

Inputs: task_id (required), action, status, objective, +4 more. Returns: ok, result_version

codex_historyB
Read-onlyIdempotent

Page persisted turns or items for owned conversations, including after an outage. Large items identify truncated_fields; pending approval details come from codex_review_request.

Inputs: task_id (required), kind, limit, cursor, +1 more. Returns: ok, result_version

codex_interruptA
Destructive

Ask Codex to interrupt the specified active turn. Poll for interrupted/completed; interrupt acknowledgement alone is not completion.

Inputs: task_id (required), expected_turn_id (required), request_id, operation_id. Returns: ok, result_version

codex_listB
Read-onlyIdempotent

Page persistent tasks, newest first. Large projections identify truncated_fields.

Inputs: view, limit, offset. Returns: ok, result_version

codex_modelsB
Read-onlyIdempotent

Discover model ids, supported reasoning efforts and defaults. Catalog visibility is not an entitlement guarantee.

Inputs: limit, cursor. Returns: ok, result_version

codex_plansA
Destructive

submit: spec/key; inspect: plan_id; list: offset/limit; cancel: plan_id/key. Runs bounded dependency plans through ordinary task admission. Unknown outcomes wait for explicit resume; no side effect is retried.

Inputs: action (required), spec, limit, offset, +3 more. Returns: ok, result_version

codex_projectsB
Destructive

List selected projects with offset/limit; select/create takes path. The main agent chooses an absolute project directory.

Inputs: path, limit, action, offset. Returns: ok, result_version

codex_queueC
Destructive

list takes cursor/limit; add takes prompt and optional images/context_files/skills; update also needs queued_id; delete needs queued_id; reorder needs ordered_ids; start takes optional queued_id. Mutations need an operation key.

Inputs: task_id (required), limit, action, cursor, +8 more. Returns: ok, result_version

codex_renameC
Destructive

Rename an owned native conversation.

Inputs: name (required), task_id (required), request_id, operation_id. Returns: ok, result_version

codex_requestsA
Read-onlyIdempotent

Page bounded pending approval/question summaries using cursor. Fetch complete content by id with codex_review_request before approval. Never infer approval from silence or timeout.

Inputs: limit, cursor, task_id. Returns: ok, result_version

codex_respondA
Destructive

Answer guidance or review requests. Typed decisions apply only to ask_parent. Approvals need human/relay; file accepts need proposal_hash. Denials need no human.

Inputs: response (required), request_id, proposal_hash, pending_request_id. Returns: ok, result_version

codex_resumeB
Destructive

Reconcile native history and execution intent after reconnect. No prompt or command replay. Inspect codex_history before a follow-up.

Inputs: task_id (required), request_id, operation_id. Returns: ok, result_version

codex_revertA
Destructive

Remove a selected turn and all later native conversation history. DOES NOT revert files. Requires explicit acknowledgement; local event audit remains.

Inputs: task_id (required), before_turn_id (required), confirm_history_only (required), request_id, +1 more. Returns: ok, result_version

codex_reviewB
Destructive

Start native code review of uncommitted changes, a base branch, a commit or custom instructions on an idle task. Poll for findings/results.

Inputs: task_id (required), branch, commit, target, +3 more. Returns: ok, result_version

codex_review_requestC
Destructive

Human review, or read details with offset=0. Follow next_offset and verify detail_sha256. Acceptance requires complete content.

Inputs: limit, offset, request_id, pending_request_id. Returns: ok, result_version

codex_sendB
Destructive

Send a follow-up turn or steer active work. Steering needs the current expected_turn_id; follow-ups can select a supported model/effort.

Inputs: prompt (required), task_id (required), mode, model, +8 more. Returns: ok, result_version

codex_sessionsC
Destructive

Choose workdir or project_id. list takes cursor/limit/archived; import takes thread_id, confirm_stopped=true, optional archived and an operation key. Native scope is verified before work.

Inputs: limit, action, cursor, workdir, +6 more. Returns: ok, result_version

codex_settingsA
Destructive

get reads settings. next takes model/effort/approval_mode/collaboration_mode/service_tier/access and root-only family budget (applies now; {} clears). current takes model/effort/approval_mode/service_tier and expected_turn_id. Changes need an operation key.

Inputs: task_id (required), model, scope, access, +8 more. Returns: ok, result_version

codex_skillsB
Read-onlyIdempotent

List native skills available for this project. Select enabled skills by name in start/send; no global skill configuration changes.

Inputs: task_id (required), force_reload. Returns: ok, result_version

codex_startB
Destructive

Start a persistent Codex conversation and return promptly with a task id. Poll codex_events and handle pending_requests until the turn finishes.

Inputs: prompt (required), name, model, access, +12 more. Returns: ok, result_version

codex_statusB
Read-onlyIdempotent

Check installed Codex, sign-in type, pending request summaries and broker health.

Inputs: requests_limit, requests_cursor. Returns: ok, result_version

codex_subagentsC
Read-onlyIdempotent

Page verified descendants; parent events include child requests. refresh=false uses offset; refresh=true uses cursor. Respect can_accept_direct_input.

Inputs: task_id (required), limit, cursor, offset, +2 more. Returns: ok, result_version

codex_terminalsB
Destructive

list takes cursor/limit; terminate takes process_id; clean stops all background terminals. Mutations need an operation key. No arbitrary shell or stdin.

Inputs: task_id (required), limit, action, cursor, +3 more. Returns: ok, result_version

codex_usageA
Read-onlyIdempotent

Read native account rate limits/remaining allowance. Does not buy credits or change billing.

Inputs: no named parameters. Returns: ok, result_version

codex_worktreesB
Destructive

plan/create: repo or project_id, name, optional base; create also plan_id/key. inspect: project_id or path, offset/limit. handoff: finished task_id. cleanup: project_id, optional keep_branch, key. Except inspect, needs worktrees=true. Never merges/pushes.

Inputs: action (required), base, name, path, +9 more. Returns: ok, result_version

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3/5.0

    Scored across 34 tools

    Disambiguation3/5

    Most tools map to distinct Codex lifecycle operations, but several boundaries are subtle: codex_review vs codex_review_request, codex_requests vs codex_respond, and codex_events vs codex_history can easily be confused. The dense descriptions help, but the agent must parse a lot to choose correctly.

    Naming Consistency3/5

    All tools use a consistent codex_ snake_case prefix, but the suffix style mixes verbs, nouns, and plural resource containers (codex_start, codex_get, codex_plans, codex_settings, codex_subagents). This is readable but not a predictable verb_noun convention.

    Tool Count2/5

    34 tools is heavy for an agent-facing server and exceeds the reasonable range for smooth tool selection. The broad Codex lifecycle may justify many operations, but the surface feels overgrown and should likely be consolidated.

    Completeness5/5

    The surface covers conversation creation, resume, listing, inspection, events, history, approvals, settings, worktrees, subagents, queueing, review, deletion, and project/session handling. No obvious lifecycle gap stands out for a Codex task-management server.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers