acodex MCP
A local bridge into the running Codex desktop app for macOS: scripts and agents call its tools through a CLI or an MCP server.
- 59 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- Relaunching opens a debug port through which a local process controls the Codex app and its threads.
Install
- Works in
Manual install
uv tool install acodexNeeds macOS, the Codex app and `uv`; then `acodex config init` and `acodex codex relaunch --yes`.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Relaunching opens a debug port through which a local process controls the Codex app and its threads.
This is third-party code. Review the repository files before installing.
What it does
acodex connects scripts and agents to a running Codex desktop app. It relaunches Codex with a Chrome DevTools Protocol debug port, starts a managed HTTP/MCP server and calls the live `codex_app.*` tools your app build provides. You do not have to write CDP plumbing yourself. The CLI covers configuration checks, relaunching Codex, starting and stopping the server and listing and calling tools: `acodex tools list` shows what is available and `acodex tools call codex_app.list_threads --limit 1` calls one. The MCP-compatible server serves the same tools at `/mcp` for local automation clients.
Who it is for. People automating the Codex desktop app on macOS: scripting over threads and sessions or wiring it into another agent.
Good fit when
- A script needs the list of Codex threads and actions without manual clicks.
- Another agent must drive the Codex app through MCP.
- You need to check which `codex_app.*` tools the current build exposes.
- You need diagnostics of the link to the app through `acodex doctor --deep`.
Not a fit when
- Work happens on Windows or Linux: the relaunch flow targets macOS.
- The Codex app is absent: the bridge drives only it.
- A debug port in the app is forbidden by security policy.
Example request
Start acodex, list the Codex app tools and show the latest thread.MCP
- Transport
- http
- Authentication
- not required
Environment variables
ACODEX_CODEX_APP_PATH- Path to the Codex app when it is not in `/Applications/Codex.app`.
Limitations
macOS with `/Applications/Codex.app` installed (another path is set by `ACODEX_CODEX_APP_PATH`), Python 3.10 or newer and `uv` are required. Relaunching opens a CDP port at `http://127.0.0.1:45217` through which live tools are reachable. The tool set depends on the Codex build and may change. The server listens locally, but any process on the machine that reaches the port gets control of the app.
How to disable. Stop the server with `acodex server stop`, restart Codex normally without the debug port and remove the package with `uv tool uninstall acodex`.
FAQ
How do I install acodex?
Run `uv tool install acodex`, then `acodex config init`, `acodex codex relaunch --yes` and `acodex server start`. macOS and the Codex app are required.
Why relaunch Codex?
The app is started with a CDP debug port, by default `http://127.0.0.1:45217`. Through it acodex sees and calls the live tools.
How do I call a tool from the terminal?
Run `acodex tools list`, then `acodex tools call codex_app.list_threads --limit 1`. Simple arguments go as flags and nested ones as JSON.
How do I stop the bridge?
With `acodex server stop`. `acodex server status` shows the server state and `acodex server logs --tail 50` shows the log.
Where is the configuration?
`acodex config path` prints the path and `acodex config show` prints the contents.
Discussion
No questions or reviews yet.
Related
MCP serversOpen Computer Use
open-computer-use
An open MCP server for desktop control: the agent reads app state and clicks, types and scrolls on macOS, Linux and Windows
An MCP server that lets an agent see the screen and control macOS, Windows and Linux: screenshots, clicks, OCR and screen memory
A local macOS CLI that lets an agent read the screen via OCR, click and type, with no cloud and no vision model
Control of the macOS, Windows and Android desktop, Chrome and Electron through MCP: screenshots, OCR, clicks and typing
A Swift MCP server that lets an agent drive any macOS app: click, type and read the interface tree
A Codex plugin that speeds up Computer Use: short click and fill loops in the browser and macOS apps, with verification.
README in short
Quick start, CLI commands and a support section. The tool is presented as local automation that spares you CDP work.