# Acodex

> Local MCP automation bridge for the Codex desktop app, with CLI, HTTP server, and live codex_app.* tool access.

- **Type:** MCP server
- **Install:** `agentstack add mcp-maksimzayats-acodex`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [maksimzayats](https://agentstack.voostack.com/s/maksimzayats)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [maksimzayats](https://github.com/maksimzayats)
- **Source:** https://github.com/maksimzayats/acodex
- **Website:** http://docs.acodex.dev/

## Install

```sh
agentstack add mcp-maksimzayats-acodex
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# acodex

[](LICENSE)

**Local MCP automation for the Codex desktop app.**

acodex gives scripts, tools, and agents a local bridge into a running Codex
desktop session. It can relaunch Codex with a Chrome DevTools Protocol (CDP)
port, run a managed HTTP/MCP server, and call the live `codex_app.*` tools that
your Codex desktop build exposes.

[Quick Start](#quick-start) | [CLI](#cli) | [Support](#support) | [Contributing](CONTRIBUTING.md)

## Why acodex

- **Live Codex desktop access.** Inspect and call the tools exposed by the
  running desktop renderer without writing CDP plumbing.
- **MCP-compatible local server.** Expose Codex desktop tools at `/mcp` for
  local automation clients.
- **Practical CLI workflow.** Check configuration, relaunch Codex with CDP,
  manage the bridge server, and call tools from a terminal.

## Quick Start

Prerequisites:

- Python 3.10 or newer.
- `uv`; see the [official install guide](https://docs.astral.sh/uv/getting-started/installation/).
- macOS with Codex.app installed. The relaunch flow expects
  `/Applications/Codex.app` by default; set `ACODEX_CODEX_APP_PATH` if yours is
  elsewhere.

Install the CLI:

```sh
uv tool install acodex
```

Initialize config, launch Codex with CDP, and start the local bridge:

```sh
acodex config init
acodex codex relaunch --yes
acodex server start
```

`acodex codex relaunch --yes` starts or restarts Codex so acodex can reach the
default CDP endpoint, `http://127.0.0.1:45217`.

For deeper diagnostics after the server is running, use `acodex doctor --deep`.

List and call Codex desktop tools:

```sh
acodex tools list
acodex tools call codex_app.list_threads --limit 1
```

Stop the managed bridge when you are done:

```sh
acodex server stop
```

## CLI

Common commands:

```sh
acodex config path
acodex config show
acodex doctor --deep
acodex codex status
acodex codex relaunch --yes
acodex server start
acodex server status
acodex server logs --tail 50
acodex tools list --json
acodex tools call codex_app.list_threads --help
```

Tool calls use the MCP schema property names. Pass simple top-level arguments as
flags, or use JSON for nested input:

```sh
acodex tools call codex_app.list_threads --limit=5
acodex tools call --args-json '{"limit":5}' codex_app.list_threads
acodex tools call --output json codex_app.list_threads --limit 5
```

## Configuration

acodex reads JSON config from `~/.acodex/config.json` by default. Set
`ACODEX_CONFIG` to use a different file. Use `acodex config path` and
`acodex config show` to inspect the active path and effective values.

Essential local endpoints:

- Codex CDP: `http://127.0.0.1:45217`
- Managed server health: `http://127.0.0.1:45218/healthz`
- MCP endpoint: `http://127.0.0.1:45218/mcp`

Configuration precedence and the full defaults matrix live in
[CONTRIBUTING.md](CONTRIBUTING.md).

State-changing tool calls mutate the live Codex desktop app. Use
`acodex tools call  --help` before calling unfamiliar tools.

## Support

When setup fails, start with the built-in diagnostics and managed server logs:

```sh
acodex doctor
acodex server logs --tail 50
```

If the issue continues, open a
[GitHub issue](https://github.com/maksimzayats/acodex/issues) with what you
tried, what happened, your OS and Python version, your acodex source branch or
commit, your Codex desktop/CDP setup, and relevant command output with secrets
removed.

## Contributing

Contributor setup, architecture notes, quality gates, and documentation rules
live in [CONTRIBUTING.md](CONTRIBUTING.md). Agent-specific guidance lives in
[AGENTS.md](AGENTS.md).

## License

acodex is released under the [MIT License](LICENSE).

acodex is independently maintained and is not affiliated with, sponsored by, or
endorsed by OpenAI.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [maksimzayats](https://github.com/maksimzayats)
- **Source:** [maksimzayats/acodex](https://github.com/maksimzayats/acodex)
- **License:** MIT
- **Homepage:** http://docs.acodex.dev/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-maksimzayats-acodex
- Seller: https://agentstack.voostack.com/s/maksimzayats
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.