codex-mcp-server
4dhxm/codex-mcp-server
Model Context Protocol (MCP) server for programmatic integration with OpenAI Codex agent threads, tasks, and history.
Instalação
npx convez-ai 4dhxm/codex-mcp-server1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
Codex MCP Server
An open-source Model Context Protocol server that bridges MCP clients (Claude Desktop, Cursor, Poke, etc.) with the Codex CLI running on your machine.
Run coding tasks, manage conversation threads, fork sessions, and browse historical rolls — all through standard MCP tooling.
Prerequisites
- Node.js 22+ (required for native SQLite bindings)
- Codex CLI installed and authenticated — verify with
codex doctor
Quick Start
git clone https://github.com/4dhxm/codex-mcp-server.git
cd codex-mcp-server
npm install
npm run build
Running the Server
1. Local Transport (stdio)
For MCP clients running on the same machine (like Claude Desktop or Cursor).
node dist/index.js
Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"codex": {
"command": "node",
"args": ["/absolute/path/to/codex-mcp-server/dist/index.js"]
}
}
}
2. Remote Transport with Auto-Tunnel (Streamable HTTP + Cloudflare)
For exposing your local Codex installation to remote MCP clients (like Poke or a remote device) without dealing with routers or ngrok warning pages.
Dependency: You must have cloudflared installed. On macOS:
brew install cloudflared
node dist/index.js --http --tunnel
This starts the server and automatically spawns a free, highly-stable Cloudflare Quick Tunnel.
You can also explicitly set your API key:
node dist/index.js --http --tunnel --api-key my-secret-token
You will see output like this:
==============================================
🌐 Cloudflare tunnel established successfully!
Public URL: https://some-random-words.trycloudflare.com
MCP URL: https://some-random-words.trycloudflare.com/mcp
==============================================
Connect from your remote MCP client:
URL: https://some-random-words.trycloudflare.com/mcp
Type: Streamable HTTP
Auth: Bearer <your-api-key>
3. Local HTTP Network Transport
To run over HTTP without a public tunnel (for your local network):
node dist/index.js --http --port 8080
Authentication
API key auth is enabled by default for HTTP mode to protect your local machine from unauthorized remote access.
Provide a key via --api-key <key> flag or CODEX_MCP_API_KEY env var. If neither is set, a random secure key is generated and printed on startup.
How clients send the key — any of these work:
| Method | Example |
|---|---|
Authorization header | Authorization: Bearer sk-abc123 |
x-api-key header | x-api-key: sk-abc123 |
| Query parameter | ?apiKey=sk-abc123 |
The server intentionally avoids returning WWW-Authenticate headers to prevent MCP clients from attempting OAuth flows, ensuring simple Bearer token auth works cleanly.
Tools
| Tool | Description |
|---|---|
codex_task / codex_run | Run a coding task in a new thread |
codex_start_thread | Initialize a thread without running a turn |
codex_run_turn / codex_continue | Send a follow-up prompt to an existing thread |
codex_list_threads | List active/archived threads from local SQLite |
codex_get_thread | Get metadata and conversation history |
codex_fork_thread | Clone a thread's history into a new session |
codex_archive_thread | Archive a thread |
codex_unarchive_thread | Unarchive a thread |
codex_interrupt / codex_interrupt_turn | Abort a running turn |