Codex MCP Server
x51xxx/codex-mcp-tool
Integração Claude + Codex CLI para análise e refatoração de código avançada
Ver no GitHubMCP server que integra Claude/Cursor com Codex CLI, permitindo análise de código via referências de arquivo, conversas multi-turno, edições sandboxizadas e modo de mudanças estruturadas. Suporta modelos OSS locais, busca web e brainstorming com frameworks de design thinking.
Instalação
npx convez-ai x51xxx/codex-mcp-tool1 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
Casos de uso
- Análise arquitetural de projetos via @referências de arquivo
- Conversas multi-turno com contexto preservado sobre uma base de código
- Geração de patches estruturados para refatoração segura
- Brainstorming técnico com métodos SCAMPER e design thinking
- Execução sandboxizada de código com modelos locais (Ollama, LM Studio)
Veredito

Ferramenta madura com feature set robusto (análise de arquivos, sessões persistentes, modo sandbox, integração com modelos locais). Requer Codex CLI instalado e pré-requisitos Node.js 18+, adequada para desenvolvedores que já usam Codex e buscam potencializar análise de código no Claude/Cursor.
README
A tradução para o português deste README ainda está na fila.
Codex MCP Server
MCP server connecting Claude/Cursor to Codex CLI. Enables code analysis via @ file references, multi-turn conversations, sandboxed edits, and structured change mode.
Features
- File Analysis — Reference files with
@src/,@package.jsonsyntax - Multi-Turn Sessions — Conversation continuity with workspace isolation
- Native Resume — Uses
codex resumefor context preservation (CLI v0.36.0+) - Local OSS Models — Run with Ollama or LM Studio via
localProvider - Web Search — Research capabilities with
search: true - Sandbox Mode — Safe code execution with
--full-auto - Change Mode — Structured OLD/NEW patch output for refactoring
- Brainstorming — SCAMPER, design-thinking, lateral thinking frameworks
- Health Diagnostics — CLI version, features, and session monitoring
- Cross-Platform — Windows, macOS, Linux fully supported
Quick Start
claude mcp add codex-cli -- npx -y @trishchuk/codex-mcp-tool
Prerequisites: Node.js 18+, Codex CLI installed and authenticated.
Configuration
{
"mcpServers": {
"codex-cli": {
"command": "npx",
"args": ["-y", "@trishchuk/codex-mcp-tool"]
}
}
}
Config locations: macOS: ~/Library/Application Support/Claude/claude_desktop_config.json | Windows: %APPDATA%\Claude\claude_desktop_config.json
Usage Examples
// File analysis
'explain the architecture of @src/';
'analyze @package.json and list dependencies';
// With specific model
'use codex with model gpt-5.5 to analyze @algorithm.py';
// Multi-turn conversations (v1.4.0+)
'ask codex sessionId:"my-project" prompt:"explain @src/"';
'ask codex sessionId:"my-project" prompt:"now add error handling"';
// Brainstorming
'brainstorm ways to optimize CI/CD using SCAMPER method';
// Sandbox mode
'use codex sandbox:true to create and run a Python script';
// Web search
'ask codex search:true prompt:"latest TypeScript 5.7 features"';
// Local OSS model (Ollama)
'ask codex localProvider:"ollama" model:"qwen3:8b" prompt:"explain @src/"';
Tools
| Tool | Description |
|---|---|
ask-codex | Execute Codex CLI with file analysis, models, sessions |
brainstorm | Generate ideas with SCAMPER, design-thinking, etc. |
list-sessions | View/delete/clear conversation sessions |
health | Diagnose CLI installation, version, features |
ping / help | Test connection, show CLI help |
Models
By default the model parameter is omitted and Codex CLI applies the
default model from your ~/.codex/config.toml (e.g. model = "gpt-5.5").
Pass model only when you need to override the configured default for a
single call. Reasoning depth is calibrated per tool:
ask-codex— uses Codex CLI default reasoning (medium). PassreasoningEffort: "high"/"xhigh"for harder tasks.brainstorm,do-act,review-changes— defaultreasoningEffort: "high"(creative ideation, act-check-fix loops, and code review benefit from deeper reasoning).
| Model | Use Case |
|---|---|
gpt-5.5 | Frontier model for complex coding, research, agentic work |
gpt-5.4 | Strong model for everyday coding |
gpt-5.4-mini | Small, fast, cost-efficient for simpler coding tasks |
gpt-5.3-codex | Coding-optimized model |
gpt-5.2 | Optimized for professional work and long-running agents |
Key Features
Session Management (v1.4.0+)
Multi-turn conversations with workspace isolation:
{ "prompt": "analyze code", "sessionId": "my-session" }
{ "prompt": "continue from here", "sessionId": "my-session" }
{ "prompt": "start fresh", "sessionId": "my-session", "resetSession": true }
Environment:
CODEX_SESSION_TTL_MS- Session TTL (default: 24h)CODEX_MAX_SESSIONS- Max sessions (default: 50)
Local OSS Models (v1.6.0+)
Run with local Ollama or LM Studio instead of OpenAI:
// Ollama
{ "prompt": "analyze @src/", "localProvider": "ollama", "model": "qwen3:8b" }
// LM Studio
{ "prompt": "analyze @src/", "localProvider": "lmstudio", "model": "my-model" }
// Auto-select provider
{ "prompt": "analyze @src/", "oss": true }
Requirements: Ollama running locally with a model that supports tool calling (e.g. qwen3:8b).
Advanced Options
| Parameter | Description |
|---|---|
model | Model selection |
sessionId | Enable conversation continuity |
sandbox | Enable --full-auto mode |
search | Enable web search |
changeMode | Structured OLD/NEW edits |
addDirs | Additional writable directories |
toolOutputTokenLimit | Cap response verbosity (100-10,000) |
reasoningEffort | Reasoning depth: low, medium, high, xhigh |
oss | Use local OSS model provider |
localProvider | Local provider: lmstudio or ollama |
CLI Compatibility
| Version | Features |
|---|---|
| v0.60.0+ | GPT-5.2 model family |
| v0.59.0+ | --add-dir, token limits |
| v0.52.0+ | Native --search flag |
| v0.36.0+ | Native codex resume (sessions) |
Troubleshooting
codex --version # Check CLI version
codex login # Authenticate
Use health tool for diagnostics: 'use health verbose:true'
Migration
v2.2.x → v2.3.0: gpt-5.5 as new default, added gpt-5.4-mini, dropped retired models (gpt-5.3-codex-spark, gpt-5.2-codex, gpt-5.1-codex-max, gpt-5.1-codex-mini).
v2.0.x → v2.1.0: gpt-5.4 as new default model, updated fallback chain.
v1.5.x → v1.6.0: Local OSS model support (localProvider, oss), gpt-5.3-codex default model, xhigh reasoning effort.
v1.3.x → v1.4.0: New sessionId parameter, list-sessions/health tools, structured error handling. No breaking changes.
License
MIT License. Not affiliated with OpenAI.
Documentation | Issues | Inspired by jamubc/gemini-mcp-tool