convez.ai
MCP ServerDesenvolvimento WebIntermediário
x51xxx

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 GitHub
BomPluginScore · de 0 a 100

MCP 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-tool

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
24
Forks
8
Acompanhando
1
Saúde
57%
Último commit
há 5 dias
Versão
v2.7.0
Issues abertas
0
Contribuidores
1

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

GitHub Release npm version npm downloads License: MIT

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.json syntax
  • Multi-Turn Sessions — Conversation continuity with workspace isolation
  • Native Resume — Uses codex resume for 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

ToolDescription
ask-codexExecute Codex CLI with file analysis, models, sessions
brainstormGenerate ideas with SCAMPER, design-thinking, etc.
list-sessionsView/delete/clear conversation sessions
healthDiagnose CLI installation, version, features
ping / helpTest 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). Pass reasoningEffort: "high" / "xhigh" for harder tasks.
  • brainstorm, do-act, review-changes — default reasoningEffort: "high" (creative ideation, act-check-fix loops, and code review benefit from deeper reasoning).
ModelUse Case
gpt-5.5Frontier model for complex coding, research, agentic work
gpt-5.4Strong model for everyday coding
gpt-5.4-miniSmall, fast, cost-efficient for simpler coding tasks
gpt-5.3-codexCoding-optimized model
gpt-5.2Optimized 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

ParameterDescription
modelModel selection
sessionIdEnable conversation continuity
sandboxEnable --full-auto mode
searchEnable web search
changeModeStructured OLD/NEW edits
addDirsAdditional writable directories
toolOutputTokenLimitCap response verbosity (100-10,000)
reasoningEffortReasoning depth: low, medium, high, xhigh
ossUse local OSS model provider
localProviderLocal provider: lmstudio or ollama

CLI Compatibility

VersionFeatures
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

Ver o original no GitHub

Bom para

Relacionados