Codex MCP Server

Bridge between Claude and OpenAI's Codex CLI — get AI-powered code analysis, generation, and review right in your editor.

graph LR
    A[Claude Code] --> B[Codex MCP Server]
    B --> C[Codex CLI]
    C --> D[OpenAI API]

    style A fill:#FF6B35
    style B fill:#4A90E2
    style C fill:#00D4AA
    style D fill:#FFA500

Quick Start

1. Install Codex CLI

npm i -g @openai/codex
codex login --api-key "your-openai-api-key"

2. Add to Claude Code

claude mcp add codex-cli -- npx -y codex-mcp-server

3. Start Using

Ask codex to explain this function
Use codex to refactor this code for better performance
Use review to check my uncommitted changes

One-Click Install

Tools

| Tool | Description | |------|-------------| | codex | AI coding assistant with session support, model selection, and structured output metadata | | review | AI-powered code review for uncommitted changes, branches, or commits | | listSessions | View active conversation sessions | | ping | Test server connection | | help | Get Codex CLI help |

Examples

Code analysis:

Use codex to analyze this authentication logic for security issues

Multi-turn conversations:

Use codex with sessionId "refactor" to analyze this module
Use codex with sessionId "refactor" to implement your suggestions

Passing a sessionId creates the session on first use, so listSessions will show it (for this server instance) and subsequent calls can resume context.

Code review:

Use review with base "main" to check my PR changes
Use review with uncommitted true to review my local changes

Advanced options:

Use codex with model "o3" and reasoningEffort "high" for complex analysis
Use codex with fullAuto true and sandbox "workspace-write" for automated tasks
Use codex with callbackUri "http://localhost:1234/callback" for static callbacks
Use codex to return structuredContent with threadId metadata when available

Requirements

• Codex CLI v0.75.0+ — Install with npm i -g @openai/codex or brew install codex
• OpenAI API key — Run codex login --api-key "your-key" to authenticate

Codex 0.87 Compatibility

• Thread ID + structured output: When Codex CLI emits threadId, this server returns it in content metadata and structuredContent, and advertises an outputSchema for structured responses.

Documentation

• API Reference — Full tool parameters and response formats
• Session Management — How conversations work
• Codex CLI Integration — Version compatibility and CLI details

Environment Variables

• CODEX_MCP_CALLBACK_URI: Static MCP callback URI passed to Codex when set (overridden by callbackUri tool arg)

Development

pnpm install   # Install dependencies
pnpm dev       # Development mode
pnpm build     # Build for production
pnpm test      # Run tests

Related Projects

• gemini-mcp-server — MCP server for Gemini CLI with 1M+ token context, web search, and media analysis

License

ISC