convez.ai
MCP Server
4dhxm

codex-mcp-server

4dhxm/codex-mcp-server

Ver no GitHub
InicialPluginScore · de 0 a 100

Model Context Protocol (MCP) server for programmatic integration with OpenAI Codex agent threads, tasks, and history.

Instalação

$npx convez-ai 4dhxm/codex-mcp-server

1 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

Estrelas
4
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

Codex MCP Server

TypeScript MCP License

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:

MethodExample
Authorization headerAuthorization: Bearer sk-abc123
x-api-key headerx-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

ToolDescription
codex_task / codex_runRun a coding task in a new thread
codex_start_threadInitialize a thread without running a turn
codex_run_turn / codex_continueSend a follow-up prompt to an existing thread
codex_list_threadsList active/archived threads from local SQLite
codex_get_threadGet metadata and conversation history
codex_fork_threadClone a thread's history into a new session
codex_archive_threadArchive a thread
codex_unarchive_threadUnarchive a thread
codex_interrupt / codex_interrupt_turnAbort a running turn

License

Apache 2.0

Ver o original no GitHub

Bom para

Relacionados