Codex CLI MCP Server

An 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.

Features

- 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

Installation

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
`

Available Tools

$3

Execute Codex with comprehensive parameter support for code analysis, generation, and assistance.

Parameters:
- prompt (required): Your query or instruction
- model (optional): gpt-5 (default and only supported model)
- sandbox (optional): read-only, workspace-write, danger-full-access
- approval (optional): untrusted, on-failure, on-request, never
- image (optional): Image file path(s) to include
- config (optional): Configuration overrides
- timeout (optional): Maximum execution time

Example:
`
ask-codex "Explain this code: @main.py" sandbox="read-only"
`

$3

Non-interactive Codex execution for automation workflows.

Parameters:
- prompt (required): Command or instruction
- model (optional): Always gpt-5
- sandbox (optional): Sandbox mode
- timeout (optional): Execution timeout

$3

Apply the latest Codex-generated diff to your git repository.

Parameters:
- dryRun (optional): Preview changes without applying
- validate (optional): Validate before applying

$3


- ping: Test MCP connection
- help: Show detailed help information
- version: Display version information

Configuration

$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
``

Acknowledgments

This project is based on the excellent Gemini MCP Tool by jamubc. We adapted their architecture and patterns to create this Codex CLI integration.

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

Support

- GitHub Issues: Report bugs and feature requests
- OpenAI Codex: https://github.com/openai/codex