MCP server for OpenAI Codex CLI integration
npm install codex-cli-mcp-toolAn MCP server that allows Claude Code to interact with the OpenAI Codex CLI. If you have a ChatGPT subscription and a claude code subscription, you can use this tool to get the benefits of both, as a $20 ChatGPT subscription gives you access to GPT-5 for free in Codex CLI.
- Complete Codex Integration: Access all Codex CLI capabilities through MCP
- GPT-5 Model: Powered by OpenAI's most capable model
- Sandbox Safety: Configurable execution modes (read-only, workspace-write, full-access)
- Progress Tracking: Real-time updates for long-running operations
- Git Integration: Apply Codex-generated diffs directly to repositories
- Flexible Configuration: Environment variables and config file support
1. Install Codex CLI (required):
``bash`
npm install -g @openai/codex
2. Add to Claude Code using npx:
`bash`
claude mcp add codex-cli-mcp-tool -- npx -y codex-cli-mcp-tool
`
Or install globally first:
bash`
npm install -g codex-cli-mcp-tool
3. Configure Authentication:
`bash
# Option 1: Use API key
export OPENAI_API_KEY=your-api-key
# Option 2: Login with ChatGPT account
codex login
`
Parameters:
- prompt (required): Your query or instructionmodel
- (optional): gpt-5 (default and only supported model)sandbox
- (optional): read-only, workspace-write, danger-full-accessapproval
- (optional): untrusted, on-failure, on-request, neverimage
- (optional): Image file path(s) to includeconfig
- (optional): Configuration overridestimeout
- (optional): Maximum execution time
Example:
``
ask-codex "Explain this code: @main.py" sandbox="read-only"
Parameters:
- prompt (required): Command or instructionmodel
- (optional): Always gpt-5sandbox
- (optional): Sandbox modetimeout
- (optional): Execution timeout
Parameters:
- dryRun (optional): Preview changes without applyingvalidate
- (optional): Validate before applying
: Test MCP connection
- help: Show detailed help information
- version: Display version informationConfiguration
$3
`bash
OPENAI_API_KEY=sk-... # OpenAI API key
CODEX_MODEL=gpt-5 # Default model
CODEX_SANDBOX_MODE=read-only # Default sandbox mode
`$3
`toml
[model]
provider = "openai"
default = "gpt-5"
reasoning_effort = "medium"[sandbox]
default_mode = "read-only"
permissions = ["disk-read-access"]
[approval]
policy = "untrusted"
trusted_commands = ["ls", "cat", "grep"]
`Sandbox Modes
- read-only: Safe exploration, no file modifications
- workspace-write: Limited modifications within project
- danger-full-access: Full system access (requires confirmation)
Examples
$3
`
ask-codex "Review this function for security issues: @auth.py"
`$3
`
ask-codex "Generate unit tests for the User class" sandbox="workspace-write"
`$3
`
ask-codex "Fix the bug in login function" approval="on-request"
`$3
`
ask-codex "Create a new React component for user profile" sandbox="workspace-write"
`$3
`
ask-codex "Refactor this code to use async/await"
apply-diff validate=true
`Troubleshooting
$3
1. Codex CLI not found:
`bash
npm install -g @openai/codex
`2. Authentication failed:
`bash
# Set API key
export OPENAI_API_KEY=your-key
# Or login
codex login
`3. Permission denied:
- Use appropriate sandbox mode
- Check approval policy settings
- Verify file permissions
4. Rate limits:
- Wait before retrying
- Check OpenAI account quota
$3
Enable debug logging:
`bash
DEBUG=true codex-cli-mcp-tool
`Development
$3
`bash
git clone
cd codex-cli-tool
npm install
npm run build
npm run dev
`$3
`bash
npm test
npm run lint
``This project is based on the excellent Gemini MCP Tool by jamubc. We adapted their architecture and patterns to create this Codex CLI integration.
MIT License - see LICENSE file for details.
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request
- GitHub Issues: Report bugs and feature requests
- OpenAI Codex: https://github.com/openai/codex