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

Related MCP server: pokeclaw

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:

The server intentionally avoids returning WWW-Authenticate headers to prevent MCP clients from attempting OAuth flows, ensuring simple Bearer token auth works cleanly.

Tools

License

Apache 2.0