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.
An MCP server that lets any LLM drive your local Codex CLI.
The calling model sends a task in plain English. Codex writes and runs code inside an isolated workspace folder on your machine. The server returns Codex's output, the list of files it created, and the images inline.
Codex generates images natively, so codex_generate_image needs no image API key — your
existing codex login is enough.
This runs code on your computer. Anything that can call these tools can make Codex execute code as you, inside its sandbox. Read SECURITY.md before using it.
Node.js 20 or newer
Codex CLI installed and logged in
Windows, macOS or Linux
Related MCP server: Codex MCP Server
New to this? Follow the step-by-step setup guide instead, which covers finding your paths, configuring each client, verifying it works, and troubleshooting.
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 buildFull walkthrough with per-OS paths and troubleshooting: SETUP.md.
This is a stdio server: the client launches it as a child process. There is no URL and nothing listens on a port.
Use absolute paths for command and for CODEX_BIN. MCP clients launch servers with a
minimal environment in which bare node and codex may not resolve.
Add 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 fine.
Find the right paths with which node / which codex (macOS, Linux) or
(Get-Command node).Source / (Get-Command codex).Source (PowerShell).
claude mcp add codex -s user -- node /absolute/path/to/codex-local-mcp/dist/index.jsAny MCP client that can launch a stdio server works. Point it at
node /absolute/path/to/dist/index.js.
Tool | Arguments | Description |
|
| Run any task. Blocks until Codex finishes. |
|
| Generate images. The prompt is passed through as written. |
|
| Read a file from a workspace. |
Reuse the same workspace name across calls to keep working on the same files.
codex_generate_image defaults to quality: "low" and size: "1024x1024" — a fast draft.
Raise quality to high for final assets. open defaults to true and opens each image in
your default viewer, because MCP clients deliver tool-result images to the model's context
and do not render them into the chat for you.
All optional, set through 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 killed. |
|
| Ceiling a caller may request. |
|
| Output cap; the head and tail are kept. |
|
| Above this, a downscaled preview is inlined instead. |
|
| Cap on reported changed files. |
|
| Set |
Codex runs as --sandbox workspace-write: it can read and write only inside the workspace
folder, plus reach the network. Workspace names that would escape the root are refused.
A few decisions worth knowing about:
Artifacts are found by filesystem diff. The workspace is snapshotted (path → mtime+size) before and after each run, so whatever Codex does, new files are detected. No output parsing.
The prompt travels on stdin (codex exec ... -), so prompt text is never shell-quoted
and cannot break out into the command line.
Budgets are counted in base64 characters, not file bytes. Encoding inflates data by 4/3, so a budget expressed in file bytes overshoots what the client actually receives by a third. Images are downscaled until their encoded form fits, and a per-response budget caps all of them together. Originals on disk are never modified.
Full-resolution files are linked, not embedded. Every reported file also comes back as an
MCP resource_link. The server declares the resources capability and serves workspace
files through resources/read, so a client can fetch the original on demand instead of
having megabytes pushed into every response. Reads outside the workspace root are refused.
Generated images open in the OS viewer, since clients don't render tool-result images.
Timeouts kill the whole process tree, so a stuck build leaves no orphans.
npm test # 11 tests against a fake Codex - no CLI or API key needed
npm run buildSee CLAUDE.md for architecture and the invariants to preserve, and CONTRIBUTING.md before opening a pull request.
CI runs the build, the test suite and npm audit on Ubuntu, Windows and macOS against
Node 20 and 22, plus weekly CodeQL analysis.
Please read SECURITY.md. Report vulnerabilities privately through GitHub's Security → Report a vulnerability, not as a public issue.
MIT © OSS Malaysia
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.
| Name | Required | Description | Default |
|---|---|---|---|
| open | No | Open the generated images in the user's default image viewer. Default true, because MCP clients do not render tool-result images into the chat. | |
| size | No | Pixel size, e.g. "1024x1024" (fastest, the default), "1536x1024" landscape, "1024x1536" portrait, "2048x2048", "3840x2160". | |
| count | No | How many images. Default 1. | |
| prompt | Yes | What the image should depict. | |
| quality | No | Generation quality. Default "low" - fastest, good for drafts. Use "high" for final assets. | |
| workspace | No | Workspace folder name. Defaults to a new folder. | |
| timeout_sec | No | Seconds before Codex is killed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It covers several behaviors: prompt is passed through as written, returns saved file paths, shows images inline, downscales previews for large files, and defaults to a fast low-quality draft. It does not mention side effects like file overwriting or permissions, but for a generation tool these are not critical. The disclosure is reasonably thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with each sentence contributing distinct information: purpose, prompt behavior, return format, and default quality tradeoff. It is front-loaded with the primary purpose, and there is no fluff or repetition. Every sentence earns its place, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 7 parameters all have schema descriptions, and the description covers the core behavior, return format, and default quality, the definition is quite complete. It lacks explicit mention of installation requirements or error handling, but the title and context imply a local CLI. The description adequately covers what an agent needs to call the tool correctly, including the key behavioral nuances.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining that the prompt is passed through as written (nuance not in schema) and by providing usage guidance for quality ('raise quality for final assets') that goes beyond the schema's generic enum descriptions. It also mentions the default size and quality, reinforcing the schema. This extra context justifies a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Generate' and the resource 'images' via the local Codex CLI, making the tool's purpose explicit. It also distinguishes from siblings like codex_run and codex_read_artifact by focusing on image generation, and even mentions return behavior (file paths and inline display) which reinforces the tool's unique role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus the siblings. However, the purpose is clear enough that an agent could infer that image generation belongs here, and it gives practical guidance on quality settings (draft vs final). But there is no explicit 'use this for images, use codex_run for code execution' or any exclusion criteria, so it's implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Path to the file, relative to the workspace root or absolute inside it. | |
| max_bytes | No | Refuse files larger than this. Default 5000000. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It adds useful detail by stating that images come back as image content and everything else as text, and the verb 'Read' implies a non-mutating operation. It does not cover error cases or permissions, but for this simple read tool that is a minor gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler. The purpose is front-loaded, and the second sentence efficiently clarifies the output format, which is the key behavioral detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with only two parameters and no output schema, the description plus schema cover the essential invocation information: purpose, path semantics, size limit, and output type. It is slightly light on failure behavior, but nothing critical is missing for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters. The description adds a little context by framing path as a file in a Codex workspace, but it does not meaningfully expand on parameter semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Read one file from a Codex workspace', and explains the target use case ('artifacts that were too large to inline'). It is clearly distinct from codex_run and codex_generate_image in both action and resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear condition for use: when a Codex artifact was too large to inline. It does not explicitly name alternatives or exclusions, but the context is sufficient to distinguish it from its siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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. Blocking: it does not return until Codex finishes.
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | Override the Codex model for this run. | |
| prompt | Yes | The task for Codex, written as you would to a developer. | |
| workspace | No | Relative workspace folder name under the workspace root. Reuse the same name to continue working on the same files. Defaults to a new timestamped folder. | |
| timeout_sec | No | Seconds before Codex is killed. Default 300. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does this well by stating execution capabilities, workspace isolation, return contents, and blocking behavior ('it does not return until Codex finishes'). It does not mention potential error conditions or broader side effects, but it covers the most important operational consequences for an agent deciding to call the tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loads the core purpose, and includes only essential behavioral details. Every sentence contributes: purpose, capability/return, and blocking behavior. There is no redundant wording or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description appropriately explains return values ('returns its output plus any files it created') and the blocking nature of the call. It omits error-handling details or security caveats, but for a task-execution tool the core needs are covered. Sibling differentiation is implicitly handled through capability emphasis.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and all four parameters have clear descriptions in the schema itself. The description adds context about the isolated workspace and the blocking execution model, which indirectly relates to the workspace and timeout parameters, but it does not add new parameter-specific meaning beyond the schema. This matches the baseline 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies a specific verb and resource: 'Hand a natural-language task to the local Codex CLI coding agent.' It further distinguishes the tool from siblings by enumerating capabilities (write/run code, install packages, call APIs) and stating it returns output plus created files. This makes the tool's identity unambiguous relative to codex_read_artifact and codex_generate_image.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool: when you need a coding agent to execute a natural-language task in an isolated workspace. It does not explicitly name alternatives or state when not to use it, so it falls short of a 5. The implied usage context is strong enough to guide an agent without being misleading.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0codex_generate_imagecodex_read_artifactcodex_runScored across 3 tools
The three tools are largely distinct: one executes a coding agent, one reads artifact files, and one generates images. The only minor ambiguity is that codex_run's general-purpose mandate could conceptually cover image generation, but the dedicated image tool helps agents choose correctly.
All tools share a codex_ prefix and verb-first names (run, read_artifact, generate_image), which is a clear and predictable pattern. codex_run is slightly less descriptive because it omits a noun object, but it does not break the style badly enough to warrant a lower score.
Three tools is appropriate for a narrow local-Codex wrapper: each tool covers a distinct operation and none feels redundant or missing. The count is well within the ideal 3-15 range for a focused MCP server.
The server covers the core workflow of running a Codex task, inspecting generated artifacts, and generating images. Minor gaps remain, such as no explicit workspace listing, cancellation, or status operations, but agents can accomplish the primary goals with this surface.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Build Apps and run code in 30 languages — sandboxed, with persistent sessions for agent loops.
Build and supervise fleets of agents from Claude Code, Codex or Cursor. Connects over OAuth.
Coding agents build full-stack apps in persistent workspaces and share them by link.
