codex-local-mcp
This server acts as a Model Context Protocol (MCP) bridge, allowing AI clients to execute and control the local Codex CLI (code editor and image generator) directly on your machine.
Execute coding and development tasks in a secure, sandboxed local workspace using
codex_run.Generate images using the local Codex engine, supporting detailed parameters like size, quality, and format (
codex_generate_image).Handle long-running processes by managing job IDs and polling for completion (
codex_job_result).Read and retrieve artifacts (files, code, or generated images) from the sandboxed workspace (
codex_read_artifact).Connect to the server via local standard input/output (stdio) or remotely using HTTP and OAuth.
Enables AI agents to drive the local OpenAI Codex CLI, allowing them to execute coding tasks in an isolated workspace, generate images, and read the resulting artifacts.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@codex-local-mcp Write a Python script that sorts a list of numbers and save it as sort.py"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
codex-local-mcp
An MCP server that lets Claude, or any other MCP client, drive the Codex CLI on your own computer.
Ask for an image or a coding task in plain English. Codex does the work inside a sandboxed workspace folder on your machine, and the server returns Codex's output, the files it created, and image previews.
Codex generates images natively, so image generation needs no image API key. Your existing ChatGPT sign-in for Codex is enough.
This runs code on your computer. Anything that can call these tools can make Codex run code as you, inside its sandbox. Read SECURITY.md before you use it.
Choose how to run it
Windows app | Command-line server | |
Best for | Using Codex from Claude on the web, desktop, or phone | Claude Desktop, Claude Code, or other local MCP clients |
Platform | Windows 10/11 x64 | Windows, macOS, Linux |
Install | Setup EXE, no other software needed | Node.js 20+ and the Codex CLI |
Connection | Remote HTTPS through Cloudflare, with OAuth login | Local stdio, or remote HTTP with OAuth |
Guide |
Related MCP server: local-code-agent
Windows app
Download
CodexLocalMCP-<version>-windows-x64-setup.exefrom the latest release and install it.Choose a workspace folder, sign in to OpenAI, and generate an MCP password.
Select Start connection, then copy the URL.
In Claude, add the URL as a custom connector and sign in with the MCP password.
The Windows app guide shows each step with screenshots and explains how to generate images, read the activity, and fix common problems.
What the app does for you:
Sandboxed by default. Codex can write only in your workspace folder. Before each start, the app tests that the sandbox blocks access to its private data.
Secure remote access. A Cloudflare Tunnel gives Claude an HTTPS address. Use a temporary Quick Tunnel with no account, or a fixed address on your own domain.
Stays signed in. Claude stays connected for 30 days across restarts and updates.
Parallel images. A request for several images runs up to four Codex sessions at once.
Live activity. See each task's stages, settings, output files, and token usage. You can also turn on a view of the prompts that Claude sends, so you can improve them.
Signed updates. The app checks for new versions, verifies each download's signature, and reconnects after the update.
The app contains a Rust MCP service and a Rust/Tauri desktop. It does not need Node.js. See the native build instructions to build it from source.
Command-line server
The TypeScript server runs on any operating system. MCP clients start it as a local process.
Requirements
Node.js 20 or newer
Codex CLI, installed and signed in
Install
New to this? Follow the step-by-step setup guide. It covers how to find your paths, configure each client, test the setup, and fix problems.
npm install -g @openai/codex # the Codex CLI itself
codex login # one time
git clone https://github.com/ossmalaysia/codex-local-mcp.git
cd codex-local-mcp
npm install
npm run buildConnect a client
The default transport is stdio: the client starts the server as a child process. For remote access through HTTPS, see Remote access with OAuth.
Use absolute paths for command and for CODEX_BIN. MCP clients start servers with a
minimal environment, in which node and codex may not resolve.
Claude Desktop
Add this to claude_desktop_config.json, then fully quit and reopen the app.
Windows:
%APPDATA%\Claude\claude_desktop_config.jsonmacOS:
~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"codex": {
"command": "/absolute/path/to/node",
"args": ["/absolute/path/to/codex-local-mcp/dist/index.js"],
"env": {
"CODEX_BIN": "/absolute/path/to/codex",
"CODEX_MCP_ROOT": "/absolute/path/to/codex-workspaces",
"CODEX_TIMEOUT_SEC": "600"
}
}
}
}On Windows, the values look like C:/Program Files/nodejs/node.exe and
C:/Users/you/AppData/Roaming/npm/codex.cmd. Forward slashes work.
Find the paths with which node and which codex (macOS, Linux), or with
(Get-Command node).Source and (Get-Command codex).Source (PowerShell).
Claude Code
claude mcp add codex -s user -- node /absolute/path/to/codex-local-mcp/dist/index.jsOther clients
Any MCP client that can start a stdio server works. Point it at
node /absolute/path/to/dist/index.js.
Remote access with OAuth
HTTP mode serves /mcp over Streamable HTTP. It includes a browser login, OAuth discovery,
dynamic client registration, and authorization codes with PKCE S256.
This mode serves one trusted owner. All authorized clients share the local Codex account, jobs, files, and workspace root. There are no separate accounts and no isolation between clients.
First run codex login on the server machine, with the same operating system account that
starts the server. The server checks codex login status at startup and before MCP requests.
Built-in Cloudflare Tunnel
Install cloudflared first. Then run:
npm run build
npm run start:tunnelThe command asks for an administrator username and password if CODEX_MCP_PASSWORD is not set.
Use at least 24 characters for the password. These credentials stay in memory for the current
session. You never enter your OpenAI password into the MCP login page.
The server starts a Cloudflare Quick Tunnel and prints its public /mcp URL and the exact
claude mcp add command. No Cloudflare account or domain is needed. Keep the terminal open
while you use the connection, and press Ctrl+C to stop it. Each start creates a new address,
so clients must connect again.
Quick Tunnels are for testing. For a fixed address, configure a named tunnel and use the manual setup below. See Cloudflare Quick Tunnels.
For unattended startup, set CODEX_MCP_USERNAME and CODEX_MCP_PASSWORD first. You can also
set CODEX_MCP_TUNNEL=quick and run npm start. If cloudflared is not found, set
CLOUDFLARED_BIN to its absolute path. The tunnel uses a temporary empty configuration and
does not change your existing Cloudflare settings.
Manual HTTPS setup
In PowerShell:
$env:CODEX_MCP_TRANSPORT = "http"
$env:CODEX_MCP_PUBLIC_URL = "https://codex.example.com"
$env:CODEX_MCP_USERNAME = "admin"
$env:CODEX_MCP_PASSWORD = [System.Net.NetworkCredential]::new("", (Read-Host "MCP password (at least 24 characters)" -AsSecureString)).Password
$env:CODEX_MCP_ROOT = "D:/codex-workspaces"
# Set CODEX_BIN to your absolute Codex CLI path if required.
npm run build
npm startOn macOS or Linux, set the same environment variables before you run npm start.
The listener uses 127.0.0.1:3000 by default. Put an HTTPS reverse proxy or tunnel in front of
it, and forward the whole public origin, including /authorize, /login, /register,
/token, /revoke, and /.well-known/*. CODEX_MCP_PUBLIC_URL must be an HTTPS origin with no path.
For example, with Caddy:
codex.example.com {
reverse_proxy 127.0.0.1:3000
}Then connect Claude Code and complete the browser login with the administrator username and password:
claude mcp add --transport http codex-remote https://codex.example.com/mcpSee the Claude Code remote MCP documentation.
Sessions and limits
The MCP login approves access. Codex uses its own local OpenAI login, and the server never sends OpenAI tokens to clients.
Access tokens expire after 15 minutes. Refresh tokens rotate, and reuse of an old refresh token or a revocation ends the whole sign-in.
The TypeScript server keeps OAuth state in memory, so a restart requires a new sign-in. The Windows app saves sign-ins for 30 days (see native/README.md).
Login allows 10 attempts per client IP every 15 minutes.
Cross-origin browser requests to
/mcpare refused.
Variable | Default | Purpose |
|
| Set |
|
| Public HTTPS origin. Loopback HTTP is allowed for local tests. |
|
| Local listener address. |
|
| Local listener port. |
|
| Administrator login name. |
| (required in HTTP mode) | Administrator password, 24 characters to 1024 bytes. Never passed to Codex. |
| (off) | Set |
| (named mode only) | Remotely managed tunnel token. Never passed to Codex. |
| (found on PATH) | Absolute path of |
Tools
Tool | Main arguments | Description |
|
| Run any task. |
|
| Generate images. Your description is passed through as written. |
|
| Collect the result of a task that was still running. |
|
| Read a file from a workspace. |
Use the same workspace name across calls to keep working on the same files.
The Windows app guide lists the image settings and
gives example requests.
Long-running tasks
MCP clients built on the official SDK give up on a request after 60 seconds by default, and
image generation often takes longer. So a call waits up to wait_sec (default 45, maximum 50).
If Codex has finished, you get the result. If not, the call returns at once with:
status: running
job_id: a3b1d698-5754-490c-ab5d-bc1ea76149a2
workspace: /path/to/codex-workspaces/my-taskCodex keeps working. The model calls codex_job_result with the job_id until the task
finishes. Finished results stay available for one hour. Jobs are held in memory, so a server
restart loses the job_id, but the files remain in the workspace.
codex_generate_image defaults to quality: "low" and size: "1024x1024", which is a fast
draft. size must be WIDTHxHEIGHT or auto. The size is a request to the image tool, so the
result reports each image's real dimensions. open defaults to true and opens each image in
your default viewer, because MCP clients give tool-result images to the model and do not
always show them in the chat.
Images in the chat (experimental, TypeScript server only)
Set CODEX_MCP_APP_VIEW=true to show an image card inside the chat in clients that support
MCP Apps. The card shows progress and
collects the finished image itself. Other clients ignore it.
It is off by default. In Claude Desktop chats that reach the server through the desktop app's device connection, the card stopped image calls from reaching the server. Enable it only in a client where you have tested it.
Configuration
All settings are optional. Set them in the client's env block.
Variable | Default | Purpose |
|
| Root for all workspaces. Nothing is written outside it. |
|
| Absolute path to the Codex CLI. |
| (Codex default) | Model override. |
|
| Default timeout before a run is stopped. |
|
| Highest timeout a caller may request. |
|
| Output limit; the start and end are kept. |
|
| Larger images are sent as a smaller preview. |
|
| Limit on reported changed files. |
|
| Set |
|
|
|
| (Codex default) | Select |
| (none) | Read-only runtime folder for the isolated profile. Set by the Windows app. |
| (none) | Private folder that sandboxed commands cannot access. Set by the Windows app. |
|
| How long a call waits before it returns a |
|
| How many Codex jobs (and, in the Windows app, Codex processes) may run at once. The Windows app sets it from Tasks at the same time. |
|
| How long a finished result stays available. |
|
| Show images in the chat as an MCP App card. Experimental; see above. |
How it works
Workspaces are sandboxed. Workspace names that would leave the root are refused. The default
workspace-writepolicy limits writes to the workspace; the stricterisolatedprofile also limits reads.Files are found by comparing the workspace before and after each run, not by reading Codex's text output.
The prompt goes to Codex on stdin (
codex exec ... -), so prompt text can never become part of a command line.Size limits count Base64 characters, not file bytes, because encoding adds a third. Large images are reduced until the encoded preview fits. Originals are never changed.
Full-size files are linked, not embedded. Each file is also returned as an MCP
resource_linkthat a client can read withresources/read, inside the workspace root only.Timeouts stop the whole process tree, so a stuck build leaves nothing behind.
Development
npm test # uses a fake Codex: no CLI or API key needed
npm run buildSee CONTRIBUTING.md before you open a pull request, and CLAUDE.md for the architecture and the rules that the code must keep. The Windows app has its own checks in native/README.md.
CI runs the build, the tests, and npm audit on Ubuntu, Windows, and macOS with Node 20 and 22,
plus the native Rust checks and weekly CodeQL analysis.
Versioning
The npm package follows Semantic Versioning, with releases created from Conventional Commits. The Windows app has its own version number. All releases and their notes are on the Releases page.
While the major version is 0, a minor release can contain breaking changes. The release notes
always state them.
Security
Read SECURITY.md. Report vulnerabilities privately through GitHub's Security → Report a vulnerability, not as a public issue.
License
MIT © OSS Malaysia
Available Tools
4 toolscodex_generate_imageGenerate images via the local Codex CLIA
Generate images with the local Codex CLI. The prompt is passed through as written. Returns the saved file paths and shows the images inline, downscaling a preview when a file is too large to inline. Defaults to a fast low-quality 1024x1024 draft; raise quality for final assets. Image generation often takes longer than wait_sec, in which case this returns status: running and a job_id; call codex_job_result with it to collect the images.
Inputs: prompt (required), open, size, count, +10 more.
codex_job_resultCollect the result of a running Codex jobA
Get the result of a codex_run or codex_generate_image call that returned status: running. Waits up to wait_sec for the job to finish; if it is still running, call again. Results stay available for 60 minutes after the job finishes.
Inputs: job_id (required), wait_sec.
codex_read_artifactRead a file produced by CodexA
Read one file from a Codex workspace, for artifacts that were too large to inline. Images come back as image content, everything else as text.
Inputs: path (required), max_bytes.
codex_runRun a task with the local Codex CLIA
Hand a natural-language task to the local Codex CLI coding agent. Codex can write and run code, install packages and call APIs inside an isolated workspace folder, then this returns its output plus any files it created. If Codex takes longer than wait_sec, this returns status: running and a job_id instead; call codex_job_result with it to collect the result.
Inputs: prompt (required), model, wait_sec, workspace, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a distinct role: reading artifacts, running Codex tasks, generating images, and polling job results. codex_run and codex_generate_image overlap somewhat since image generation could be requested through run, but the dedicated tool and async behavior make the boundary clear enough.
All tools share a consistent codex_ snake_case prefix. The verb/noun pattern is mostly predictable, though codex_job_result is noun-based rather than verb-based like the others.
Four tools is well matched to a local Codex CLI wrapper: submit work, generate images, poll async jobs, and read large artifacts. Each tool earns its place without bloat.
The core lifecycle is covered: run tasks, generate images, poll async results, and retrieve artifacts. Minor gaps include no explicit job cancellation or job listing, but agents can work around these by polling or ignoring stale jobs.
Maintenance
Related MCP Connectors
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Persistent cloud workspaces for AI agents: run commands, edit files, use git and a browser.
Your AI agent is smart enough to code all day. Local firewall & zero-loss runtime.
Related MCP Servers
- AlicenseCqualityDmaintenanceConnects AI assistants like Claude to the Codex CLI for code analysis, editing, and execution. Supports file references with @ syntax, sandboxed code execution with approval workflows, and structured code changes for automated refactoring and documentation.8131 npm176MIT
- FlicenseNot gradedqualityDmaintenanceEnables external AI (ChatGPT, Claude) to securely access a local workspace via Cloudflare Tunnel, providing file operations, shell commands, Git operations, and more with bearer token authentication and sandbox isolation.1-
- AlicenseNot gradedqualityBmaintenanceEnables ChatGPT conversations to directly inspect local workspaces and delegate coding tasks to a local Codex agent, with controlled concurrency, reusable sessions, and task/usage tracking.597 npmMIT
- AlicenseAqualityCmaintenanceEnables MCP-compatible coding agents to execute the local Codex CLI as a coding agent, including code reviews, session resume/fork, and CLI diagnostics.911 npmMIT