OpenAI Codex MCP Server

OpenAI Codex MCP 服务

将 OpenAI Codex CLI 封装为 MCP（模型上下文协议）服务，以便与 Claude 集成。

🚀 功能

此 MCP 服务提供以下工具：

• codex_agent：功能全面的工具，可使用 OpenAI Codex CLI 的所有功能

  • 代码生成、解释、调试和重构
  • 安全分析、测试创建和文档生成
  • 多模态支持（图像输入）
  • 支持多个 AI 提供商
  • 3 级自动化模式（建议／自动编辑／全自动）

• codex_interactive：用于启动交互式会话的工具

🔌 支持的模式

• stdio 模式：使用标准输入／输出（适用于 Claude Desktop）
• SSE 模式：使用服务器发送事件（适用于 Web API）

📋 前提条件

1. OpenAI Codex CLI：

   npm install -g @openai/codex
   

2. Python 3.12 或更高版本

3. 环境设置：将 .env.example 复制为 .env 并进行配置

🛠️ 安装

1. 克隆仓库

git clone https://github.com/Tomatio13/openai-codex-mcp.git
cd openai-codex-mcp

2. 设置

./setup.sh

3. 启动服务

stdio 模式（适用于 Claude Desktop）

./run.sh

SSE 模式（适用于 Web API）

./run_sse.sh [port] [host]

# Examples:
./run_sse.sh 8080 0.0.0.0  # Port 8080, listen on all interfaces
./run_sse.sh              # Default: localhost:8000

手动启动

# stdio mode
python codex_server.py --mode stdio

# SSE mode
python codex_server.py --mode sse --port 8000 --host localhost

也可以通过一条命令完成设置并启动：

./setup_and_run.sh

手动安装

# Install dependencies
pip install -e .

# Start server
python codex_server.py

🔧 Claude 配置

stdio 模式（推荐）

要在 Claude Desktop 中使用 MCP 服务，请将以下内容添加到配置文件中：

macOS

~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "openai-codex": {
      "command": "python",
      "args": ["/path/to/openai-codex-mcp/codex_server.py", "--mode", "stdio"],
      "env": {
        "PATH": "/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

Windows

%APPDATA%\Claude\claude_desktop_config.json：

{
  "mcpServers": {
    "openai-codex": {
      "command": "python",
      "args": ["C:\\path\\to\\openai-codex-mcp\\codex_server.py", "--mode", "stdio"],
      "env": {
        "PATH": "C:\\Program Files\\nodejs;C:\\Windows\\System32"
      }
    }
  }
}

SSE 模式

在 SSE 模式下，可以通过 HTTP 端点访问 MCP 服务：

# Start server
./run_sse.sh 8000

# Available endpoints
# GET  http://localhost:8000/sse - SSE connection
# POST http://localhost:8000/message - Send message

💡 使用方法

在 Claude Desktop 中配置 MCP 服务后，可以按以下方式使用这些工具：

基本代码生成

@openai-codex codex_agent prompt="Create a Python function to calculate Fibonacci numbers"

针对特定任务进行优化

@openai-codex codex_agent prompt="Explain this code" task_type="code-explanation"
@openai-codex codex_agent prompt="Fix the bug in utils.py" task_type="debugging" model="o4-preview"
@openai-codex codex_agent prompt="Check for security vulnerabilities" task_type="security"

自动化级别设置

# Suggestions only (default, safest)
@openai-codex codex_agent prompt="Refactor this code" approval_mode="suggest"

# Auto-edit (automatic file read/write, command execution requires confirmation)
@openai-codex codex_agent prompt="Explain this codebase" approval_mode="auto-edit"

# Full auto (fully automatic execution in network-disabled sandbox)
@openai-codex codex_agent prompt="Create and run tests" approval_mode="full-auto"

多模态（图像输入）

@openai-codex codex_agent prompt="Implement this UI design" images=["design.png"] task_type="code-generation"

使用不同的 AI 提供商

@openai-codex codex_agent prompt="Review this code" provider="azure" model="gpt-4.1"
@openai-codex codex_agent prompt="Explain this" provider="ollama" model="llama3"

交互式会话

@openai-codex codex_interactive initial_prompt="Tell me about the project structure" approval_mode="auto-edit"

🎯 任务类型

使用 task_type 参数，生成针对特定任务优化的提示词：

• general：常规编码协助（默认）
• code-generation：生成新代码
• code-explanation：解释现有代码
• debugging：查找并修复错误
• refactoring：改进代码结构
• testing：编写或修复测试
• security：安全分析与修复
• documentation：生成或改进文档

🤖 AI 提供商

通过 provider 参数支持以下 AI 提供商：

• openai：OpenAI（默认）
• azure：Azure OpenAI
• gemini：Google Gemini
• ollama：Ollama（本地模型）
• mistral：Mistral AI
• deepseek：DeepSeek
• xai：xAI
• groq：Groq

🔒 审批模式

• suggest：仅提出更改建议，所有操作都需要审批（最安全）
• auto-edit：可自动读取和写入文件，执行 shell 命令时会询问
• full-auto：在禁用网络的沙盒中完全自主运行（功能最强大）

🛡️ 安全性

• full-auto 模式在禁用网络的沙盒中运行，以确保安全
• 文件操作仅限于当前工作目录
• 除非处于 full-auto 模式，否则所有 shell 命令都需要明确审批

🐛 故障排除

常见问题

1. “codex command not found”

   npm install -g @openai/codex
   

2. 脚本权限被拒绝

   chmod +x *.sh
   

3. Python 版本问题

   • 确保已安装 Python 3.12+
   • 使用虚拟环境：python3 -m venv venv && source venv/bin/activate

4. MCP 连接问题

   • 检查 Claude Desktop 配置文件语法
   • 确认文件路径为绝对路径
   • 配置更改后重启 Claude Desktop

📝 许可证

MIT License with Attribution——详情请参阅 LICENSE 文件。

🤝 贡献

欢迎贡献！请随时提交 Pull Request。

📞 支持

如果遇到任何问题或有疑问，请在 GitHub 上提出 issue。

---

为 Claude + OpenAI Codex 社区倾心打造 ❤️