{
  "markdown": "# Codex MCP Server\n\n<div align=\"center\">\n\n[![GitHub Release](https://img.shields.io/github/v/release/x51xxx/codex-mcp-tool?logo=github&label=GitHub)](https://github.com/x51xxx/codex-mcp-tool/releases)\n[![npm version](https://img.shields.io/npm/v/@trishchuk/codex-mcp-tool)](https://www.npmjs.com/package/@trishchuk/codex-mcp-tool)\n[![npm downloads](https://img.shields.io/npm/dt/@trishchuk/codex-mcp-tool)](https://www.npmjs.com/package/@trishchuk/codex-mcp-tool)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n\n</div>\n\nMCP server connecting Claude/Cursor to Codex CLI. Enables code analysis via `@` file references, multi-turn conversations, sandboxed edits, and structured change mode.\n\n## Features\n\n- **File Analysis** — Reference files with `@src/`, `@package.json` syntax\n- **Multi-Turn Sessions** — Conversation continuity with workspace isolation\n- **Native Resume** — Uses `codex resume` for context preservation (CLI v0.36.0+)\n- **Local OSS Models** — Run with Ollama or LM Studio via `localProvider`\n- **Web Search** — Research capabilities with `search: true`\n- **Sandbox Mode** — Safe automation with explicit sandbox and approval policies\n- **Change Mode** — Structured OLD/NEW patch output for refactoring\n- **Brainstorming** — SCAMPER, design-thinking, lateral thinking frameworks\n- **Health Diagnostics** — CLI version, features, and session monitoring\n- **Cross-Platform** — Windows, macOS, Linux fully supported\n\n## Quick Start\n\n```bash\nclaude mcp add codex-cli -- npx -y @trishchuk/codex-mcp-tool\n```\n\n**Prerequisites:** Node.js 18+, [Codex CLI](https://github.com/openai/codex) installed and authenticated.\n\n### Configuration\n\n```json\n{\n  \"mcpServers\": {\n    \"codex-cli\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@trishchuk/codex-mcp-tool\"]\n    }\n  }\n}\n```\n\n**Config locations:** macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` | Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n## Usage Examples\n\n```javascript\n// File analysis\n'explain the architecture of @src/';\n'analyze @package.json and list dependencies';\n\n// With specific model\n'use codex with model gpt-5.6-sol to analyze @algorithm.py';\n\n// Multi-turn conversations (v1.4.0+)\n'ask codex sessionId:\"my-project\" prompt:\"explain @src/\"';\n'ask codex sessionId:\"my-project\" prompt:\"now add error handling\"';\n\n// Brainstorming\n'brainstorm ways to optimize CI/CD using SCAMPER method';\n\n// Sandbox mode\n'use codex sandbox:true to create and run a Python script';\n\n// Web search\n'ask codex search:true prompt:\"latest TypeScript 5.7 features\"';\n\n// Local OSS model (Ollama)\n'ask codex localProvider:\"ollama\" model:\"qwen3:8b\" prompt:\"explain @src/\"';\n```\n\n## Tools\n\n| Tool             | Description                                                         |\n| ---------------- | ------------------------------------------------------------------- |\n| `ask-codex`      | Execute Codex CLI with files, models, sessions, and safety controls |\n| `batch-codex`    | Run multiple atomic Codex tasks sequentially or concurrently        |\n| `review-changes` | Run the native non-interactive Codex review command                 |\n| `do-act`         | Execute, verify with a shell command, and retry fixes               |\n| `brainstorm`     | Generate ideas with structured creative frameworks                  |\n| `list-sessions`  | View, delete, or clear MCP conversation mappings                    |\n| `list-skills`    | List skills visible from the selected workspace                     |\n| `health`         | Diagnose CLI installation, version, features, and sessions          |\n| `fetch-chunk`    | Retrieve a chunk from cached change-mode output                     |\n| `ping`           | Test the MCP connection                                             |\n| `help`           | Return current `codex --help` output                                |\n| `version`        | Report Codex CLI, Node.js, platform, and package versions           |\n| `timeout-test`   | Exercise keepalive and timeout behavior                             |\n\n## Models\n\nBy default the `model` parameter is **omitted** and Codex CLI applies the\ndefault model from your `~/.codex/config.toml` (for example `model = \"gpt-5.6-sol\"`).\nPass `model` only when you need to override the configured default for a\nsingle call. Reasoning depth is calibrated per tool:\n\n- `ask-codex` — uses the Codex CLI default reasoning (medium). Increase it only when the task needs more planning or checking.\n- `brainstorm`, `do-act`, `review-changes` — default `reasoningEffort: \"high\"` (creative ideation, act-check-fix loops, and code review benefit from deeper reasoning).\n\n| Model           | Recommendation                                         |\n| --------------- | ------------------------------------------------------ |\n| `gpt-5.6-sol`   | Complex, ambiguous, high-value work; strongest default |\n| `gpt-5.6-terra` | Everyday coding with a better capability/cost balance  |\n| `gpt-5.6-luna`  | Clear, repeatable, high-volume tasks                   |\n| `gpt-5.5`       | Previous-generation fallback                           |\n| `gpt-5.4`       | Professional coding fallback                           |\n| `gpt-5.4-mini`  | Small, fast, cost-efficient fallback                   |\n\nGPT-5.6 Sol and Terra can expose `max` and `ultra` reasoning. `ultra` may\ndelegate work to subagents; most tasks should remain on `medium` or `high`.\n\n## Key Features\n\n### Session Management (v1.4.0+)\n\nMulti-turn conversations with workspace isolation:\n\n```javascript\n{ \"prompt\": \"analyze code\", \"sessionId\": \"my-session\" }\n{ \"prompt\": \"continue from here\", \"sessionId\": \"my-session\" }\n{ \"prompt\": \"start fresh\", \"sessionId\": \"my-session\", \"resetSession\": true }\n```\n\n**Environment:**\n\n- `CODEX_SESSION_TTL_MS` - Session TTL (default: 24h)\n- `CODEX_MAX_SESSIONS` - Max sessions (default: 50)\n\n### Codex CLI version\n\nRequires **Codex CLI `0.95.0` or newer**. On older versions the server fails\nwith an explicit upgrade message rather than silently dropping unsupported\nflags. Upgrade with `npm install -g @openai/codex@latest`; run the `health` tool\nto see the detected version.\n\n### Troubleshooting: \"codex not found\"\n\nMCP clients launched from a GUI (Dock, Finder, Start menu) inherit a minimal\n`PATH` that excludes Homebrew, nvm, and volta directories, so `codex` may work\nfrom a terminal but not from the app. The server searches those locations\nautomatically; if it still cannot find the CLI, pin it explicitly:\n\n```json\n{ \"env\": { \"CODEX_CLI_PATH\": \"/opt/homebrew/bin/codex\" } }\n```\n\nFind the value with `which codex`. Run the `health` tool to see which\nexecutable was resolved and how.\n\n### Local OSS Models (v1.6.0+)\n\nRun with local Ollama or LM Studio instead of OpenAI:\n\n```javascript\n// Ollama\n{ \"prompt\": \"analyze @src/\", \"localProvider\": \"ollama\", \"model\": \"qwen3:8b\" }\n\n// LM Studio\n{ \"prompt\": \"analyze @src/\", \"localProvider\": \"lmstudio\", \"model\": \"my-model\" }\n\n// Auto-select provider\n{ \"prompt\": \"analyze @src/\", \"oss\": true }\n```\n\n**Requirements:** [Ollama](https://ollama.com) running locally with a model that supports tool calling (e.g. `qwen3:8b`).\n\n### Advanced Options\n\n| Parameter              | Description                                       |\n| ---------------------- | ------------------------------------------------- |\n| `model`                | Model selection                                   |\n| `sessionId`            | Enable conversation continuity                    |\n| `sandbox`              | Compatibility automation: workspace-write + never |\n| `search`               | Enable web search                                 |\n| `changeMode`           | Structured OLD/NEW edits                          |\n| `addDirs`              | Additional writable directories                   |\n| `toolOutputTokenLimit` | Cap response verbosity (100-10,000)               |\n| `reasoningEffort`      | low, medium, high, xhigh, max, ultra              |\n| `oss`                  | Use local OSS model provider                      |\n| `localProvider`        | Local provider: `lmstudio` or `ollama`            |\n| `strictConfig`         | Fail on unknown Codex configuration keys          |\n| `ephemeral`            | Do not persist Codex session files                |\n| `ignoreUserConfig`     | Ignore `$CODEX_HOME/config.toml`                  |\n| `ignoreRules`          | Ignore execpolicy `.rules` files                  |\n\n## CLI Compatibility\n\nValidated against Codex CLI `0.144.3`. The server keeps older feature guards,\nbut current releases are recommended. Notable current behavior:\n\n- `--full-auto` and approval policy `on-failure` have been removed by Codex CLI.\n- MCP `sandbox: true` / `fullAuto: true` remain compatibility aliases for\n  `--sandbox workspace-write --ask-for-approval never`; they do not bypass the sandbox.\n- Native `--search` is used without the deprecated `web_search_request` feature.\n- Current `exec` flags include `--strict-config`, `--ephemeral`,\n  `--ignore-user-config`, and `--ignore-rules`.\n\n## Troubleshooting\n\n```bash\ncodex --version    # Check CLI version\ncodex login        # Authenticate\n```\n\nUse `health` tool for diagnostics: `'use health verbose:true'`\n\n## Migration\n\n**v2.3.x → v2.4.0:** Codex CLI `0.144.3` compatibility audit; added GPT-5.6\nSol/Terra/Luna, `max`/`ultra` reasoning, current exec flags, native-only search,\nand safe compatibility handling for the removed `--full-auto` flag and\n`on-failure` approval policy.\n\n**Current CLI compatibility:** added GPT-5.6 Sol/Terra/Luna, `max`/`ultra`\nreasoning, current exec flags, native-only search, and safe expansion of the\nremoved `--full-auto` compatibility option.\n\n**v2.2.x → v2.3.0:** `gpt-5.5` as new default, added `gpt-5.4-mini`, dropped retired models (`gpt-5.3-codex-spark`, `gpt-5.2-codex`, `gpt-5.1-codex-max`, `gpt-5.1-codex-mini`).\n\n**v2.0.x → v2.1.0:** `gpt-5.4` as new default model, updated fallback chain.\n\n**v1.5.x → v1.6.0:** Local OSS model support (`localProvider`, `oss`), `gpt-5.3-codex` default model, `xhigh` reasoning effort.\n\n**v1.3.x → v1.4.0:** New `sessionId` parameter, `list-sessions`/`health` tools, structured error handling. No breaking changes.\n\n## License\n\nMIT License. Not affiliated with OpenAI.\n\n---\n\n[Documentation](https://x51xxx.github.io/codex-mcp-tool/) | [Issues](https://github.com/x51xxx/codex-mcp-tool/issues) | Inspired by [jamubc/gemini-mcp-tool](https://github.com/jamubc/gemini-mcp-tool)\n",
  "bytes": 10487,
  "sha": "ac9cde14e2460697c8fbb44f6473872b1481379844882a2dc665b54dfc4608cb",
  "repo_slug": "x51xxx/codex-mcp-tool",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_x51xxx_codex_mcp_tool_c98ee402/readme"
}