# Codex MCP

A lightweight [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that exposes the local [Codex CLI](https://github.com/openai/codex) (`codex`) to MCP-compatible coding agents.

The project intentionally keeps the architecture small: MCP tools validate inputs, a thin CLI adapter executes `codex exec` (and friends), and `codex_raw` provides an escape hatch for CLI options that are added in future Codex releases.

## Features

- Run Codex as a local coding agent through MCP (`codex exec`).
- Run non-interactive code reviews (`codex exec review`).
- Resume or fork previous sessions (`codex exec resume` / `codex exec fork`).
- Control common CLI options such as model, sandbox policy, approval behavior, extra directories, images, and output handling.
- Inspect version, login status, and diagnostics (`codex doctor`).
- Pass arbitrary CLI arguments through `codex_raw` for forward compatibility.
- No shell execution: arguments are passed directly to the `codex` process (`shell: false`).
- Optional server-wide model override via an environment variable (see below).

## Requirements

- Node.js 18+
- Codex CLI installed and authenticated (`codex login`)
- `codex` available on `PATH`
- An MCP-compatible client

If `codex` is not on `PATH`, set `CODEX_MCP_CMD` to the executable path.

```bash
CODEX_MCP_CMD=/custom/path/codex
```

Windows PowerShell:

```powershell
$env:CODEX_MCP_CMD = "C:\path\to\codex.exe"
```

## Forcing a specific model

Every tool that runs the agent (`codex_run`, `codex_review`, `codex_resume`, `codex_fork`, and `codex_raw` when its first argument is `exec`) accepts a `model` input. If you set the `CODEX_MCP_MODEL` environment variable on the MCP server process, it overrides the model for **every** such call, regardless of what the caller (or a raw argument list) requests. This is useful when you want to pin the server to a single model — for cost control, quota limits, or consistency — no matter what any individual tool call asks for.

```bash
CODEX_MCP_MODEL=your-model-id
```

The override is applied last, after stripping any `-m`/`--model` flag or `-c model=...` config override already present in the constructed arguments, so it always wins. It is never applied to subcommands that don't accept a model (`--version`, `login status`, `help`, `doctor`, ...), so those keep working normally even when the override is set.

## Quick Start

The recommended setup is through npm. You do not need to clone this repository or install the MCP server manually.

### Claude Code

```bash
claude mcp add --scope user codex -- npx -y codex-mcp
```

Verify the server:

```bash
claude mcp list
```

If `codex` is not on `PATH`, or you want to pin the model:

```bash
claude mcp add --scope user \
  --env CODEX_MCP_CMD=/custom/path/codex \
  --env CODEX_MCP_MODEL=your-model-id \
  codex -- npx -y codex-mcp
```

### Gemini CLI

```bash
gemini mcp add --scope user codex npx -y codex-mcp
```

Verify:

```bash
gemini mcp list
```

### Cursor

```json
{
  "mcpServers": {
    "codex": {
      "command": "npx",
      "args": ["-y", "codex-mcp"]
    }
  }
}
```

### Windsurf

```json
{
  "mcpServers": {
    "codex": {
      "command": "npx",
      "args": ["-y", "codex-mcp"]
    }
  }
}
```

### Cline / Roo Code / Other MCP Clients

```json
{
  "command": "npx",
  "args": ["-y", "codex-mcp"]
}
```

If the client supports environment variables, `CODEX_MCP_CMD` and `CODEX_MCP_MODEL` can be set there as well.

## Local Development

```bash
git clone https://github.com/alvarosw/codex-mcp.git
cd codex-mcp
npm install
npm start
```

No build step is required.

### Testing

`npm test` runs a static syntax check only — it makes no network calls and costs nothing.

`npm run test:live` drives the real MCP server end to end over stdio against a real, authenticated Codex CLI (in a throwaway temp git repo it creates and cleans up). It exercises every tool, including verifying that `CODEX_MCP_MODEL` (if set) wins over a deliberately wrong model passed in a tool call or smuggled into `codex_raw` arguments. This makes real model calls and is not run automatically — you need `codex login` completed first, and it will consume real quota/tokens against whichever model resolves for the call:

```bash
CODEX_MCP_MODEL=your-model-id npm run test:live
```

`CODEX_MCP_MODEL` is optional for this script; without it, the override-specific assertions are skipped and the rest of the suite still runs against your account's default configured model.

## Tools

### `codex_run`

Run Codex as an agent non-interactively (`codex exec`) with common CLI controls: prompt, model, sandbox policy, approval routing, extra directories, images, working directory, ephemeral/persisted sessions, and raw passthrough args.

Example:

```json
{
  "prompt": "Review the authentication implementation and identify security issues.",
  "cwd": "/workspace/project",
  "sandbox": "workspace-write",
  "addDirs": ["/workspace/shared"]
}
```

### `codex_review`

Runs `codex exec review` non-interactively against the current repository. Supports `uncommitted`, `base`, `commit`, and `title`, plus a custom review `prompt`.

### `codex_resume`

Resumes a previous session (`codex exec resume`) by `sessionId`, or the most recent one if omitted, optionally sending a new `prompt`.

### `codex_fork`

Forks a previous session (`codex exec fork`) by `sessionId` into a new session, optionally sending a `prompt`.

### `codex_version`

Returns the installed Codex CLI version.

### `codex_login_status`

Runs `codex login status` to check authentication state.

### `codex_doctor`

Runs `codex doctor --json` for install, auth, config, and connectivity diagnostics.

### `codex_help`

Shows CLI help. A command can be provided for command-specific help.

### `codex_raw`

Runs `codex` with an arbitrary argument array. This is the compatibility escape hatch for flags or commands not covered by the convenience tools. The model override, if set, still applies when the first argument is `exec`.

Example:

```json
{
  "args": ["mcp", "list"]
}
```

## Architecture

```text
src/
├── index.js   # MCP server and tool registration
├── tools.js   # Tool behavior and response formatting (JSONL event parsing)
└── codex.js   # Thin process adapter for the codex CLI + model-override enforcement
```

Dependency direction:

```text
MCP transport
    ↓
tool handlers
    ↓
codex CLI adapter
    ↓
local codex executable
```

There is intentionally no service container, repository layer, or framework abstraction. The project has one external process boundary and keeps that boundary explicit.

Tools that invoke `codex exec*` request `--json` internally so output can be parsed reliably; each tool's text response is the agent's final message(s), with the full parsed event stream, command executions, token usage, and thread id available in `structuredContent` for programmatic consumers.

## Security Notes

`codex_raw` can execute arbitrary Codex CLI arguments with the permissions of the user running the MCP server. The server itself does not invoke a shell, so tool arguments are not shell-interpreted, but `codex` still has whatever permissions its sandbox and approval settings grant it.

`dangerouslyBypassApprovalsAndSandbox` skips all confirmation prompts and sandboxing. Only use it when you explicitly trust the task and an already-isolated workspace.

Environment variables passed through the `env` field are inherited by the `codex` process. Avoid sending secrets through MCP tool arguments unless necessary.

## License

MIT