Codex MCP Tool

1# Codex MCP Tool
2 
3<div align="center">
4 
5[![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)
6[![npm version](https://img.shields.io/npm/v/@trishchuk/codex-mcp-tool)](https://www.npmjs.com/package/@trishchuk/codex-mcp-tool)
7[![npm downloads](https://img.shields.io/npm/dt/@trishchuk/codex-mcp-tool)](https://www.npmjs.com/package/@trishchuk/codex-mcp-tool)
8[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
9 
10</div>
11 
12MCP server connecting Claude/Cursor to Codex CLI. Enables code analysis via `@` file references, multi-turn conversations, sandboxed edits, and structured change mode.
13 
14## Features
15 
16- **File Analysis** — Reference files with `@src/`, `@package.json` syntax
17- **Multi-Turn Sessions** — Conversation continuity with workspace isolation
18- **Native Resume** — Uses `codex resume` for context preservation (CLI v0.36.0+)
19- **Local OSS Models** — Run with Ollama or LM Studio via `localProvider`
20- **Web Search** — Research capabilities with `search: true`
21- **Sandbox Mode** — Safe code execution with `--full-auto`
22- **Change Mode** — Structured OLD/NEW patch output for refactoring
23- **Brainstorming** — SCAMPER, design-thinking, lateral thinking frameworks
24- **Health Diagnostics** — CLI version, features, and session monitoring
25- **Cross-Platform** — Windows, macOS, Linux fully supported
26 
27## Quick Start
28 
29```bash
30claude mcp add codex-cli -- npx -y @trishchuk/codex-mcp-tool
31```
32 
33**Prerequisites:** Node.js 18+, [Codex CLI](https://github.com/openai/codex) installed and authenticated.
34 
35### Configuration
36 
37```json
38{
39  "mcpServers": {
40    "codex-cli": {
41      "command": "npx",
42      "args": ["-y", "@trishchuk/codex-mcp-tool"]
43    }
44  }
45}
46```
47 
48**Config locations:** macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` | Windows: `%APPDATA%\Claude\claude_desktop_config.json`
49 
50## Usage Examples
51 
52```javascript
53// File analysis
54'explain the architecture of @src/';
55'analyze @package.json and list dependencies';
56 
57// With specific model
58'use codex with model gpt-5.3-codex to analyze @algorithm.py';
59 
60// Multi-turn conversations (v1.4.0+)
61'ask codex sessionId:"my-project" prompt:"explain @src/"';
62'ask codex sessionId:"my-project" prompt:"now add error handling"';
63 
64// Brainstorming
65'brainstorm ways to optimize CI/CD using SCAMPER method';
66 
67// Sandbox mode
68'use codex sandbox:true to create and run a Python script';
69 
70// Web search
71'ask codex search:true prompt:"latest TypeScript 5.7 features"';
72 
73// Local OSS model (Ollama)
74'ask codex localProvider:"ollama" model:"qwen3:8b" prompt:"explain @src/"';
75```
76 
77## Tools
78 
79| Tool            | Description                                            |
80| --------------- | ------------------------------------------------------ |
81| `ask-codex`     | Execute Codex CLI with file analysis, models, sessions |
82| `brainstorm`    | Generate ideas with SCAMPER, design-thinking, etc.     |
83| `list-sessions` | View/delete/clear conversation sessions                |
84| `health`        | Diagnose CLI installation, version, features           |
85| `ping` / `help` | Test connection, show CLI help                         |
86 
87## Models
88 
89Default: `gpt-5.3-codex` with fallback → `gpt-5.2-codex` → `gpt-5.1-codex-max` → `gpt-5.2`
90 
91| Model                | Use Case                                 |
92| -------------------- | ---------------------------------------- |
93| `gpt-5.3-codex`      | Latest frontier agentic coding (default) |
94| `gpt-5.2-codex`      | Frontier agentic coding                  |
95| `gpt-5.1-codex-max`  | Deep and fast reasoning                  |
96| `gpt-5.1-codex-mini` | Cost-efficient quick tasks               |
97| `gpt-5.2`            | Broad knowledge, reasoning and coding    |
98 
99## Key Features
100 
101### Session Management (v1.4.0+)
102 
103Multi-turn conversations with workspace isolation:
104 
105```javascript
106{ "prompt": "analyze code", "sessionId": "my-session" }
107{ "prompt": "continue from here", "sessionId": "my-session" }
108{ "prompt": "start fresh", "sessionId": "my-session", "resetSession": true }
109```
110 
111**Environment:**
112 
113- `CODEX_SESSION_TTL_MS` - Session TTL (default: 24h)
114- `CODEX_MAX_SESSIONS` - Max sessions (default: 50)
115 
116### Local OSS Models (v1.6.0+)
117 
118Run with local Ollama or LM Studio instead of OpenAI:
119 
120```javascript
121// Ollama
122{ "prompt": "analyze @src/", "localProvider": "ollama", "model": "qwen3:8b" }
123 
124// LM Studio
125{ "prompt": "analyze @src/", "localProvider": "lmstudio", "model": "my-model" }
126 
127// Auto-select provider
128{ "prompt": "analyze @src/", "oss": true }
129```
130 
131**Requirements:** [Ollama](https://ollama.com) running locally with a model that supports tool calling (e.g. `qwen3:8b`).
132 
133### Advanced Options
134 
135| Parameter              | Description                               |
136| ---------------------- | ----------------------------------------- |
137| `model`                | Model selection                           |
138| `sessionId`            | Enable conversation continuity            |
139| `sandbox`              | Enable `--full-auto` mode                 |
140| `search`               | Enable web search                         |
141| `changeMode`           | Structured OLD/NEW edits                  |
142| `addDirs`              | Additional writable directories           |
143| `toolOutputTokenLimit` | Cap response verbosity (100-10,000)       |
144| `reasoningEffort`      | Reasoning depth: low, medium, high, xhigh |
145| `oss`                  | Use local OSS model provider              |
146| `localProvider`        | Local provider: `lmstudio` or `ollama`    |
147 
148## CLI Compatibility
149 
150| Version  | Features                         |
151| -------- | -------------------------------- |
152| v0.60.0+ | GPT-5.2 model family             |
153| v0.59.0+ | `--add-dir`, token limits        |
154| v0.52.0+ | Native `--search` flag           |
155| v0.36.0+ | Native `codex resume` (sessions) |
156 
157## Troubleshooting
158 
159```bash
160codex --version    # Check CLI version
161codex login        # Authenticate
162```
163 
164Use `health` tool for diagnostics: `'use health verbose:true'`
165 
166## Migration
167 
168**v1.5.x → v1.6.0:** Local OSS model support (`localProvider`, `oss`), `gpt-5.3-codex` default model, `xhigh` reasoning effort.
169 
170**v1.3.x → v1.4.0:** New `sessionId` parameter, `list-sessions`/`health` tools, structured error handling. No breaking changes.
171 
172## License
173 
174MIT License. Not affiliated with OpenAI.
175 
176---
177 
178[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)
179