https://github.com/tuannvm/codex-mcp-server
MCP server wrapper for OpenAI Codex CLI that enables Claude Code to leverage Codex's AI capabilities directly.
https://github.com/tuannvm/codex-mcp-server
claude-code codex cursor mcp
Last synced: 6 days ago
JSON representation
MCP server wrapper for OpenAI Codex CLI that enables Claude Code to leverage Codex's AI capabilities directly.
- Host: GitHub
- URL: https://github.com/tuannvm/codex-mcp-server
- Owner: tuannvm
- Created: 2025-08-18T03:39:12.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-01-19T16:25:10.000Z (24 days ago)
- Last Synced: 2026-01-21T00:33:50.646Z (22 days ago)
- Topics: claude-code, codex, cursor, mcp
- Language: TypeScript
- Homepage: https://docs.tuannvm.com/codex-mcp-server
- Size: 404 KB
- Stars: 102
- Watchers: 0
- Forks: 24
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Codex MCP Server
[](https://www.npmjs.com/package/codex-mcp-server)
[](https://www.npmjs.com/package/codex-mcp-server)
[](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
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
[](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)
[](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)
[](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 |
| `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](docs/api-reference.md)** — Full tool parameters and response formats
- **[Session Management](docs/session-management.md)** — How conversations work
- **[Codex CLI Integration](docs/codex-cli-integration.md)** — 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