Skip to main content
Glama
easy-codex-mcp
by dazebug

easy-codex-mcp

An MCP server that lets any MCP-compatible AI assistant have read-only conversations with OpenAI Codex CLI.

No complex setup β€” just codex login and you're ready.

Why?

Sometimes your AI assistant needs a second opinion. easy-codex-mcp bridges the gap by letting Claude, Cursor, or any MCP client consult Codex for code analysis, review, and Q&A β€” all in a non-destructive, read-only sandbox.

  • πŸ”’ Read-only by design β€” Codex runs in sandbox mode. It reads your code but never modifies files or runs commands.

  • πŸ’¬ Conversational β€” Start a thread and continue it later with full context preserved.

  • πŸ”§ Zero config β€” No API keys to manage in your MCP config. Just log in to Codex CLI once.

Related MCP server: codex-cli-architect-mcp

Quick Start

1. Install Codex CLI

npm install -g @openai/codex
codex login

2. Add to your MCP client

Claude Code (recommended):

claude mcp add easy-codex uvx -- --from git+https://github.com/dazebug/easy-codex-mcp easy-codex

Claude Desktop β€” add to your claude_desktop_config.json:

{
  "mcpServers": {
    "easy-codex": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/dazebug/easy-codex-mcp", "easy-codex"]
    }
  }
}

Other MCP clients β€” use the same config format with uvx as the command.

3. Use it

Your AI assistant now has two new tools:

Tool

Description

start_new_conversation

Start a fresh conversation with Codex

continue_conversation

Resume a previous conversation using thread_id

Example prompts to your AI assistant:

  • "Ask Codex to review this file for potential bugs"

  • "Get Codex's opinion on the architecture of this module"

  • "Have Codex explain how the authentication flow works"

Tools

start_new_conversation

Start a new read-only conversation with Codex.

Parameters:

  • prompt (required) β€” What to ask Codex.

  • working_directory (optional) β€” Directory for Codex to work in.

Returns: { "thread_id": "...", "response": "..." }

continue_conversation

Resume a previous conversation with full context.

Parameters:

  • thread_id (required) β€” Thread ID from a previous conversation.

  • prompt (required) β€” Follow-up question.

  • working_directory (optional) β€” Directory for Codex to work in.

Returns: { "thread_id": "...", "response": "..." }

How It Works

Your AI Assistant  ──MCP──▢  easy-codex-mcp  ──CLI──▢  Codex (read-only sandbox)
       β”‚                          β”‚                          β”‚
       β”‚   "Review this code"     β”‚   codex e --json "..."   β”‚
       │◀─────────────────────────│◀──────────────────────── β”‚
       β”‚   thread_id + response   β”‚   JSONL output           β”‚
  1. Your assistant calls the MCP tool with a prompt

  2. easy-codex-mcp spawns codex CLI in read-only sandbox mode

  3. Codex analyzes your code and responds

  4. The response + thread_id are returned to your assistant

  5. Use thread_id to continue the conversation later

Requirements

  • Python 3.12+

  • OpenAI Codex CLI (npm install -g @openai/codex)

  • Codex CLI logged in (codex login)

Development

git clone https://github.com/dazebug/easy-codex-mcp.git
cd easy-codex-mcp
uv sync

# Run tests
uv run pytest

# Dev mode
uv run mcp dev src/easy_codex/server.py

License

MIT

Available Tools

2 tools
continue_conversationA

Continue an existing Codex conversation.

Resumes a previous conversation using thread_id to maintain context. Same read-only sandbox limitations as start_new_conversation apply.

When to use:

  1. Asking follow-up questions based on previous analysis

  2. Continuing multi-step analysis on the same codebase

  3. Sending additional requests while maintaining conversation context

Args: thread_id: thread_id from a previous conversation. prompt: Follow-up prompt to send to codex. Use @filepath to mention files. working_directory: Directory path for codex to work in (optional).

Returns: Dict with thread_id and response.

Inputs: prompt (required), thread_id (required), working_directory.

start_new_conversationA

Start a new conversation with OpenAI Codex CLI.

Runs codex CLI in read-only sandbox mode and returns a thread_id for continuing the conversation later.

Limitations:

  • Runs in read-only sandbox β€” cannot modify files or execute shell commands.

  • Use only for read-only tasks: code reading, analysis, and Q&A.

When to use:

  1. Analyzing the structure or behavior of a codebase

  2. Code review or root cause analysis of bugs

  3. Generating explanations or documentation drafts for code

  4. Getting refactoring or architecture suggestions

Args: prompt: Prompt to send to codex. Use @filepath to mention files. working_directory: Directory path for codex to work in (optional).

Returns: Dict with thread_id and response.

Inputs: prompt (required), working_directory.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.6/5.0

    Scored across 2 tools

    Disambiguation5/5

    The two tools have clearly distinct purposes: one starts a new conversation and returns a thread_id, the other continues an existing conversation using that thread_id. There is no overlap or ambiguity between them.

    Naming Consistency5/5

    Both tool names follow the same verb_noun pattern with snake_case, using 'start_new_' and 'continue_' as clear action prefixes. This consistency makes the API predictable and easy to navigate.

    Tool Count4/5

    At only two tools, the count is on the low end but perfectly appropriate for the server's narrow purpose of managing Codex conversations. The tools cover the essential start/continue workflow without unnecessary additions.

    Completeness4/5

    The tool surface covers the primary conversation lifecycle (start and continue) with no dead ends. Minor gaps such as the absence of explicit conversation termination or history listing are acceptable given the read-only, session-based scope.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers