Skip to main content
Glama
codex-local-mcp

codex-local-mcp

by ossmalaysia

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.

WARNING

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

Windows app guide

Setup guide

Related MCP server: local-code-agent

Windows app

  1. Download CodexLocalMCP-<version>-windows-x64-setup.exe from the latest release and install it.

  2. Choose a workspace folder, sign in to OpenAI, and generate an MCP password.

  3. Select Start connection, then copy the URL.

  4. 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 build

Connect 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.json

  • macOS: ~/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.js

Other 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:tunnel

The 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 start

On 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/mcp

See 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 /mcp are refused.

Variable

Default

Purpose

CODEX_MCP_TRANSPORT

stdio

Set http for remote access.

CODEX_MCP_PUBLIC_URL

http://127.0.0.1:3000

Public HTTPS origin. Loopback HTTP is allowed for local tests.

CODEX_MCP_HOST

127.0.0.1

Local listener address.

CODEX_MCP_PORT

3000

Local listener port.

CODEX_MCP_USERNAME

admin

Administrator login name.

CODEX_MCP_PASSWORD

(required in HTTP mode)

Administrator password, 24 characters to 1024 bytes. Never passed to Codex.

CODEX_MCP_TUNNEL

(off)

Set quick or named to start a Cloudflare Tunnel with HTTP mode.

CODEX_MCP_TUNNEL_TOKEN

(named mode only)

Remotely managed tunnel token. Never passed to Codex.

CLOUDFLARED_BIN

(found on PATH)

Absolute path of cloudflared.

Tools

Tool

Main arguments

Description

codex_run

prompt, workspace?, timeout_sec?, model?, reasoning_effort?, wait_sec?

Run any task.

codex_generate_image

prompt, count?, size?, quality?, output_format?, background?, target_file_kb?, workspace?, open?, wait_sec?

Generate images. Your description is passed through as written.

codex_job_result

job_id, wait_sec?

Collect the result of a task that was still running.

codex_read_artifact

path, max_bytes?

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-task

Codex 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

CODEX_MCP_ROOT

~/.codex-mcp/workspaces

Root for all workspaces. Nothing is written outside it.

CODEX_BIN

codex

Absolute path to the Codex CLI.

CODEX_MODEL

(Codex default)

Model override.

CODEX_TIMEOUT_SEC

300

Default timeout before a run is stopped.

CODEX_MAX_TIMEOUT_SEC

1800

Highest timeout a caller may request.

CODEX_MAX_OUTPUT_CHARS

40000

Output limit; the start and end are kept.

CODEX_MAX_INLINE_IMAGE_BYTES

1048576

Larger images are sent as a smaller preview.

CODEX_MAX_REPORTED_FILES

200

Limit on reported changed files.

CODEX_NETWORK_ACCESS

true

Set false to block network access for Codex commands.

CODEX_SANDBOX_MODE

workspace-write

isolated allows only the workspace and runtime paths; read-only refuses writes. The Windows app uses isolated.

CODEX_WINDOWS_SANDBOX

(Codex default)

Select mxc or elevated. An explicit choice never falls back to another backend.

CODEX_RUNTIME_ROOT

(none)

Read-only runtime folder for the isolated profile. Set by the Windows app.

CODEX_PRIVATE_ROOT

(none)

Private folder that sandboxed commands cannot access. Set by the Windows app.

CODEX_WAIT_SEC

45

How long a call waits before it returns a job_id. At most 50.

CODEX_MAX_RUNNING_JOBS

4

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.

CODEX_JOB_RETENTION_SEC

3600

How long a finished result stays available.

CODEX_MCP_APP_VIEW

false

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-write policy limits writes to the workspace; the stricter isolated profile 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_link that a client can read with resources/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 build

See 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 tools
codex_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

    A4.2/5.0

    Scored across 4 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      D
      maintenance
      Connects 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.
      8
      131 npm
      176
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables 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
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 npm
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables MCP-compatible coding agents to execute the local Codex CLI as a coding agent, including code reviews, session resume/fork, and CLI diagnostics.
      9
      11 npm
      MIT