# Codex MCP Server

[![npm version](https://img.shields.io/npm/v/codex-mcp-server.svg)](https://www.npmjs.com/package/codex-mcp-server) [![npm downloads](https://img.shields.io/npm/dm/codex-mcp-server.svg)](https://www.npmjs.com/package/codex-mcp-server) [![license](https://img.shields.io/npm/l/codex-mcp-server.svg)](https://www.npmjs.com/package/codex-mcp-server)

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

{% @mermaid/diagram content="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

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

### 2. Add to Claude Code

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

[![VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square\&logo=visualstudiocode\&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=codex-cli\&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22codex-mcp-server%22%5D%7D) [![VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square\&logo=visualstudiocode\&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=codex-cli\&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22codex-mcp-server%22%5D%7D) [![Cursor](https://img.shields.io/badge/Cursor-Install-00D8FF?style=flat-square\&logo=cursor\&logoColor=white)](https://cursor.com/en/install-mcp?name=codex\&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoibnB4IC15IGNvZGV4LW1jcC1zZXJ2ZXIiLCJlbnYiOnt9fQ%3D%3D)

## 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                      |
| `websearch`    | Web search using Codex CLI with customizable result count and search depth                |
| `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
```

**Web search:**

```
Use websearch with query "TypeScript 5.8 new features"
Use websearch with query "Rust vs Go performance 2025" and numResults 15
Use websearch with query "React Server Components" and searchDepth "full"
```

## 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**](https://docs.tuannvm.com/docs/api-reference) — Full tool parameters and response formats
* [**Session Management**](https://docs.tuannvm.com/docs/session-management) — How conversations work
* [**Codex CLI Integration**](https://docs.tuannvm.com/docs/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

```bash
npm install    # Install dependencies
npm run dev    # Development mode
npm run build  # Build for production
npm test       # Run tests
```

## Related Projects

* [**gemini-mcp-server**](https://github.com/tuannvm/gemini-mcp-server) — MCP server for Gemini CLI with 1M+ token context, web search, and media analysis

## License

ISC