Skip to content
Back to search

codex-mcp-server

MCP server wrapper for OpenAI Codex CLI that enables Claude Code to leverage Codex's AI capabilities directly.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/tuannvm--codex-mcp-server/badge.svg)](/listings/tuannvm--codex-mcp-server)

HTML

<a href="/listings/tuannvm--codex-mcp-server"><img src="/api/listings/tuannvm--codex-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 130 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Codex MCP Server
  2. [![npm version](https://img.shields.io/npm/v/codex-mcp-server.svg)](https://www.npmjs.com/package/codex-mcp-server)
  3. [![npm downloads](https://img.shields.io/npm/dm/codex-mcp-server.svg)](https://www.npmjs.com/package/codex-mcp-server)
  4. [![license](https://img.shields.io/npm/l/codex-mcp-server.svg)](https://www.npmjs.com/package/codex-mcp-server)
  5. Bridge between Claude and OpenAI's Codex CLI — get AI-powered code analysis, generation, and review right in your editor.
  6. ```mermaid
  7. graph LR
  8. A[Claude Code] --> B[Codex MCP Server]
  9. B --> C[Codex CLI]
  10. C --> D[OpenAI API]
  11. style A fill:#FF6B35
  12. style B fill:#4A90E2
  13. style C fill:#00D4AA
  14. style D fill:#FFA500
  15. ```
  16. ## Quick Start
  17. ### 1. Install Codex CLI
  18. ```bash
  19. npm i -g @openai/codex
  20. codex login --api-key "your-openai-api-key"
  21. ```
  22. ### 2. Add to Claude Code
  23. ```bash
  24. claude mcp add codex-cli -- npx -y codex-mcp-server
  25. ```
  26. ### 3. Start Using
  27. ```
  28. Ask codex to explain this function
  29. Use codex to refactor this code for better performance
  30. Use review to check my uncommitted changes
  31. ```
  32. ## One-Click Install
  33. [![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)
  34. [![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)
  35. [![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)
  36. ## Tools
  37. | Tool | Description |
  38. |------|-------------|
  39. | `codex` | AI coding assistant with session support, model selection, and structured output metadata |
  40. | `review` | AI-powered code review for uncommitted changes, branches, or commits |
  41. | `websearch` | Web search using Codex CLI with customizable result count and search depth |
  42. | `listSessions` | View active conversation sessions |
  43. | `ping` | Test server connection |
  44. | `help` | Get Codex CLI help |
  45. ## Examples
  46. **Code analysis:**
  47. ```
  48. Use codex to analyze this authentication logic for security issues
  49. ```
  50. **Multi-turn conversations:**
  51. ```
  52. Use codex with sessionId "refactor" to analyze this module
  53. Use codex with sessionId "refactor" to implement your suggestions
  54. ```
  55. Passing a sessionId creates the session on first use, so listSessions will show
  56. it (for this server instance) and subsequent calls can resume context.
  57. **Code review:**
  58. ```
  59. Use review with base "main" to check my PR changes
  60. Use review with uncommitted true to review my local changes
  61. ```
  62. **Advanced options:**
  63. ```
  64. Use codex with model "o3" and reasoningEffort "high" for complex analysis
  65. Use codex with fullAuto true and sandbox "workspace-write" for automated tasks
  66. Use codex with callbackUri "http://localhost:1234/callback" for static callbacks
  67. Use codex to return structuredContent with threadId metadata when available
  68. ```
  69. **Web search:**
  70. ```
  71. Use websearch with query "TypeScript 5.8 new features"
  72. Use websearch with query "Rust vs Go performance 2025" and numResults 15
  73. Use websearch with query "React Server Components" and searchDepth "full"
  74. ```
  75. ## Requirements
  76. - **Codex CLI v0.75.0+** — Install with `npm i -g @openai/codex` or `brew install codex`
  77. - **OpenAI API key** — Run `codex login --api-key "your-key"` to authenticate
  78. ## Codex 0.87 Compatibility
  79. - **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.
  80. ## Documentation
  81. - **[API Reference](docs/api-reference.md)** — Full tool parameters and response formats
  82. - **[Session Management](docs/session-management.md)** — How conversations work
  83. - **[Codex CLI Integration](docs/codex-cli-integration.md)** — Version compatibility and CLI details
  84. ## Environment Variables
  85. - `CODEX_MCP_CALLBACK_URI`: Static MCP callback URI passed to Codex when set (overridden by `callbackUri` tool arg)
  86. ## Development
  87. ```bash
  88. npm install # Install dependencies
  89. npm run dev # Development mode
  90. npm run build # Build for production
  91. npm test # Run tests
  92. ```
  93. ## Related Projects
  94. - **[gemini-mcp-server](https://github.com/tuannvm/gemini-mcp-server)** — MCP server for Gemini CLI with 1M+ token context, web search, and media analysis
  95. - **[Clotch](https://github.com/tuannvm/clotch)** — Dynamic Island for Claude Code on macOS — monitor sessions across multiple machines and providers in real time
  96. ## License
  97. ISC

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.