{"_id":"@alvarosw/codex-mcp","name":"@alvarosw/codex-mcp","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@alvarosw/codex-mcp","version":"1.0.0","description":"A lightweight MCP server that exposes the local Codex CLI to MCP-compatible coding agents.","type":"module","main":"src/index.js","bin":{"codex-mcp":"src/index.js"},"scripts":{"start":"node src/index.js","test":"node --check src/index.js && node --check src/codex.js && node --check src/tools.js","test:live":"node test/smoke.mjs"},"keywords":["mcp","codex","openai","claude-code","agent"],"license":"MIT","engines":{"node":">=18"},"dependencies":{"@modelcontextprotocol/sdk":"^1.17.5","zod":"^3.23.8"},"_id":"@alvarosw/codex-mcp@1.0.0","_nodeVersion":"26.7.0","_npmVersion":"11.19.0","dist":{"integrity":"sha512-jmyls3138tJ3L/t1VZnyu6yUE+ipBNntU710o6DiB5p8Opul3q4yfGSOuEC0EQ191R7fUM8Jw2P0/KVesPkjog==","shasum":"00ad9490c26f25f9ea6ab0116802279db492f4fd","tarball":"https://registry.npmjs.org/@alvarosw/codex-mcp/-/codex-mcp-1.0.0.tgz","fileCount":7,"unpackedSize":32450,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIBBy596OQ/VCh5/ILkaU0sHVwmZm1hSmUci8YYdUaaUQAiAFEuSztVzYmHsjJo/x6Mp7YKCPAVx9KGiNsF2+Cp6QbQ=="}]},"_npmUser":{"name":"alvarosw","email":"alvarossmiguel@gmail.com"},"directories":{},"maintainers":[{"name":"alvarosw","email":"alvarossmiguel@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/codex-mcp_1.0.0_1789080451897_0.6680686803947034"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-10T22:47:31.607Z","1.0.0":"2026-09-10T22:47:32.032Z","modified":"2026-09-10T22:47:32.285Z"},"maintainers":[{"name":"alvarosw","email":"alvarossmiguel@gmail.com"}],"description":"A lightweight MCP server that exposes the local Codex CLI to MCP-compatible coding agents.","keywords":["mcp","codex","openai","claude-code","agent"],"license":"MIT","readme":"# Codex MCP\n\nA 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.\n\nThe 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.\n\n## Features\n\n- Run Codex as a local coding agent through MCP (`codex exec`).\n- Run non-interactive code reviews (`codex exec review`).\n- Resume or fork previous sessions (`codex exec resume` / `codex exec fork`).\n- Control common CLI options such as model, sandbox policy, approval behavior, extra directories, images, and output handling.\n- Inspect version, login status, and diagnostics (`codex doctor`).\n- Pass arbitrary CLI arguments through `codex_raw` for forward compatibility.\n- No shell execution: arguments are passed directly to the `codex` process (`shell: false`).\n- Optional server-wide model override via an environment variable (see below).\n\n## Requirements\n\n- Node.js 18+\n- Codex CLI installed and authenticated (`codex login`)\n- `codex` available on `PATH`\n- An MCP-compatible client\n\nIf `codex` is not on `PATH`, set `CODEX_MCP_CMD` to the executable path.\n\n```bash\nCODEX_MCP_CMD=/custom/path/codex\n```\n\nWindows PowerShell:\n\n```powershell\n$env:CODEX_MCP_CMD = \"C:\\path\\to\\codex.exe\"\n```\n\n## Forcing a specific model\n\nEvery 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.\n\n```bash\nCODEX_MCP_MODEL=your-model-id\n```\n\nThe 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.\n\n## Quick Start\n\nThe recommended setup is through npm. You do not need to clone this repository or install the MCP server manually.\n\n### Claude Code\n\n```bash\nclaude mcp add --scope user codex -- npx -y codex-mcp\n```\n\nVerify the server:\n\n```bash\nclaude mcp list\n```\n\nIf `codex` is not on `PATH`, or you want to pin the model:\n\n```bash\nclaude mcp add --scope user \\\n  --env CODEX_MCP_CMD=/custom/path/codex \\\n  --env CODEX_MCP_MODEL=your-model-id \\\n  codex -- npx -y codex-mcp\n```\n\n### Gemini CLI\n\n```bash\ngemini mcp add --scope user codex npx -y codex-mcp\n```\n\nVerify:\n\n```bash\ngemini mcp list\n```\n\n### Cursor\n\n```json\n{\n  \"mcpServers\": {\n    \"codex\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"codex-mcp\"]\n    }\n  }\n}\n```\n\n### Windsurf\n\n```json\n{\n  \"mcpServers\": {\n    \"codex\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"codex-mcp\"]\n    }\n  }\n}\n```\n\n### Cline / Roo Code / Other MCP Clients\n\n```json\n{\n  \"command\": \"npx\",\n  \"args\": [\"-y\", \"codex-mcp\"]\n}\n```\n\nIf the client supports environment variables, `CODEX_MCP_CMD` and `CODEX_MCP_MODEL` can be set there as well.\n\n## Local Development\n\n```bash\ngit clone https://github.com/alvarosw/codex-mcp.git\ncd codex-mcp\nnpm install\nnpm start\n```\n\nNo build step is required.\n\n### Testing\n\n`npm test` runs a static syntax check only — it makes no network calls and costs nothing.\n\n`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:\n\n```bash\nCODEX_MCP_MODEL=your-model-id npm run test:live\n```\n\n`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.\n\n## Tools\n\n### `codex_run`\n\nRun 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.\n\nExample:\n\n```json\n{\n  \"prompt\": \"Review the authentication implementation and identify security issues.\",\n  \"cwd\": \"/workspace/project\",\n  \"sandbox\": \"workspace-write\",\n  \"addDirs\": [\"/workspace/shared\"]\n}\n```\n\n### `codex_review`\n\nRuns `codex exec review` non-interactively against the current repository. Supports `uncommitted`, `base`, `commit`, and `title`, plus a custom review `prompt`.\n\n### `codex_resume`\n\nResumes a previous session (`codex exec resume`) by `sessionId`, or the most recent one if omitted, optionally sending a new `prompt`.\n\n### `codex_fork`\n\nForks a previous session (`codex exec fork`) by `sessionId` into a new session, optionally sending a `prompt`.\n\n### `codex_version`\n\nReturns the installed Codex CLI version.\n\n### `codex_login_status`\n\nRuns `codex login status` to check authentication state.\n\n### `codex_doctor`\n\nRuns `codex doctor --json` for install, auth, config, and connectivity diagnostics.\n\n### `codex_help`\n\nShows CLI help. A command can be provided for command-specific help.\n\n### `codex_raw`\n\nRuns `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`.\n\nExample:\n\n```json\n{\n  \"args\": [\"mcp\", \"list\"]\n}\n```\n\n## Architecture\n\n```text\nsrc/\n├── index.js   # MCP server and tool registration\n├── tools.js   # Tool behavior and response formatting (JSONL event parsing)\n└── codex.js   # Thin process adapter for the codex CLI + model-override enforcement\n```\n\nDependency direction:\n\n```text\nMCP transport\n    ↓\ntool handlers\n    ↓\ncodex CLI adapter\n    ↓\nlocal codex executable\n```\n\nThere is intentionally no service container, repository layer, or framework abstraction. The project has one external process boundary and keeps that boundary explicit.\n\nTools 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.\n\n## Security Notes\n\n`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.\n\n`dangerouslyBypassApprovalsAndSandbox` skips all confirmation prompts and sandboxing. Only use it when you explicitly trust the task and an already-isolated workspace.\n\nEnvironment variables passed through the `env` field are inherited by the `codex` process. Avoid sending secrets through MCP tool arguments unless necessary.\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-42dd719c77909a0b080e241eef1b59f2"}