使用说明

克劳德-Codex MCP 服务器

一个强大的模型上下文协议（MCP）服务器，能够实现 克劳德担任战略智囊 对代码操作、质量检查以及CI/CD工作流程实现全面的精细控制。

理念：克劳德（Claude）为智慧大脑，工具为实践之手

不同于那种将任务发送给一个黑箱（即代理委托模型）的方式，这个MCP服务器是直接给Claude（或指某特定系统/模型）的 细粒度控制 每一步都（仔细）把控/监督

能见度克劳德在每一步都能看到成果
控制克劳德在操作之间做出决策
质量门代码检查和测试防止不良代码被提交
安全秘密扫描和路径验证保护您的代码库
可审计性结构化日志记录创建了一个完整的审计追踪

建筑

Claude Code (Strategic Orchestrator)
    ↓
Claude-Codex MCP Server (Python)
    ├─ Repository Operations (read, search, write)
    ├─ Codex Integration (optional code generation)
    ├─ Quality Tools (lint, test)
    ├─ Artifact Tools (download, parse CI reports)
    ├─ Git Operations (status, commit, diff)
    └─ Security (secret scanning, path validation)

特点/功能

🔍 仓库操作

**repo_read**读取多个文件并进行安全验证
**repo_search**使用正则表达式快速进行 ripgrep 支持的代码搜索
**repo_write**编写文件时进行秘密扫描和路径检查

🤖 Codex 集成（可选）

**codex_exec**调用 Codex CLI 进行复杂代码生成
**codex_get_diff**审查Codex所做的更改
使用您现有的Codex CLI安装和身份验证

✅ 质量工具

**quality_lint**运行代码检查工具（ruff、eslint、pylint、flake8）
**quality_test**运行测试（pytest, jest, mocha, cargo）
工具和框架的自动检测

📦 艺术品工具

**artifact_download**下载并解压CI（持续集成）制品
**artifact_parse_junit**解析JUnit XML测试报告

🔧 Git 操作

**git_status**获取仓库状态（分支、暂存、修改的文件）
**git_diff**查看更改
**git_commit**创建提交
**git_log**查看提交历史

🔒 安全功能

秘密扫描（API密钥、令牌、凭证）
路径验证（阻止访问敏感目录）
可配置的允许/阻止路径模式
结构化审计日志

安装

先决条件

Python 3.11+（或“Python 3.11及以上版本”）
Codex CLI（注：Codex通常指某种代码或规范集，CLI指命令行界面，所以这里“Codex CLI”可以理解为某种基于命令行界面的Codex工具或系统，但具体翻译可能需根据上下文调整）（可选，用于代码生成）： npm install -g @openai/codex-cli
ripgrep（注：这是一个命令行工具，用于在文件中搜索文本，其名称可直译为“撕裂搜索”，但通常保留原名以指代其特定功能） （可选，用于快速搜索）：https://github.com/BurntSushi/ripgrep

安装MCP服务器

cd claude-codex-mcp
pip install -e .

配置环境

复制示例环境文件并进行自定义：

cp .env.example .env

编辑 .env:

# Security Configuration
ALLOWED_PATHS=src,tests,docs,examples,configs
BLOCKED_PATHS=~/.ssh,/etc,.env,.aws,~/.config

# Repository Configuration
DEFAULT_REPO_ROOT=.

# Logging Configuration
LOG_FILE=logs/bridge.jsonl
LOG_LEVEL=INFO

# Codex CLI Configuration (if using Codex integration)
CODEX_BINARY=codex
CODEX_DEFAULT_MODEL=o1
CODEX_TIMEOUT=300

使用方法

启动MCP服务器

服务器使用stdio传输（标准输入/输出）与Claude Code进行通信

python -m src.server

配置Claude代码

将服务器添加到您的Claude Code MCP配置中：

对于 Claude Code CLI：

编辑 ~/.config/claude-code/mcp.json （或在您的系统上找到等效选项）：

{
  "mcpServers": {
    "claude-codex-mcp": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/claude-codex-mcp",
      "env": {
        "REPO_ROOT": "/path/to/your/project"
      }
    }
  }
}

对于Claude Desktop：

编辑您的Claude桌面MCP设置，以包含：

{
  "mcpServers": {
    "claude-codex-mcp": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/claude-codex-mcp",
      "env": {
        "REPO_ROOT": "/path/to/your/project"
      }
    }
  }
}

示例工作流程

工作流1：查找并修复待办事项（TODOs）

1. Claude: "Find all TODO comments in the codebase"
   → Calls: repo_search(pattern="TODO:")

2. Claude: "Let me read these files to understand context"
   → Calls: repo_read(paths=["file1.py", "file2.py"])

3. Claude: "I'll use Codex to implement the first TODO"
   → Calls: codex_exec(instruction="Implement rate limiting at line 42")

4. Claude: "Let me review the changes"
   → Calls: codex_get_diff()

5. Claude: "Changes look good. Let me run tests"
   → Calls: quality_test(selectors=["tests/test_auth.py"])

6. Claude: "Tests pass! Committing..."
   → Calls: git_commit(message="Add rate limiting to login")

工作流程2：解析CI测试失败情况

1. Claude: "Download the test artifacts from CI"
   → Calls: artifact_download(url="https://ci.example.com/artifacts/123.zip")

2. Claude: "Parse the JUnit reports"
   → Calls: artifact_parse_junit(glob_pattern="artifacts/**/*.xml")

3. Claude: "I see 3 tests failed. Let me read those test files"
   → Calls: repo_read(paths=["tests/test_api.py"])

4. Claude: "The issue is in the auth logic. Let me check the implementation"
   → Calls: repo_search(pattern="def authenticate")

5. Claude: "Found the bug. I'll use Codex to fix it"
   → Calls: codex_exec(instruction="Fix null pointer in authenticate function")

工具参考

存储库工具

`repo_read`

{
  "name": "repo_read",
  "parameters": {
    "paths": ["src/file1.py", "src/file2.py"]
  }
}

`repo_search`

{
  "name": "repo_search",
  "parameters": {
    "pattern": "TODO:|FIXME:",
    "globs": ["*.py", "*.js"]
  }
}

`repo_write`

{
  "name": "repo_write",
  "parameters": {
    "path": "src/new_feature.py",
    "content": "def hello():\n    print('Hello')",
    "mode": "create"
  }
}

《Codex Tools》（或译为《代码工具集》）

`codex_exec`

{
  "name": "codex_exec",
  "parameters": {
    "instruction": "Add rate limiting to the login function",
    "context_files": ["src/auth.py", "src/utils.py"],
    "model": "o1",
    "sandbox": "workspace-write"
  }
}

质量工具

`quality_lint`

{
  "name": "quality_lint",
  "parameters": {
    "globs": ["src/**/*.py"],
    "linter": "ruff"
  }
}

`quality_test`

{
  "name": "quality_test",
  "parameters": {
    "selectors": ["tests/test_auth.py", "tests/unit/"],
    "framework": "pytest"
  }
}

Git 工具

`git_status`

{
  "name": "git_status",
  "parameters": {}
}

`git_commit`

{
  "name": "git_commit",
  "parameters": {
    "message": "Implement rate limiting for login endpoint",
    "files": ["src/auth.py", "tests/test_auth.py"]
  }
}

安全

路径验证

服务器限制文件访问仅限于配置的路径：

被允许: src/， tests/， docs/， examples/， configs/
被阻止: ~/.ssh， /etc， .env， .aws， ~/.config， credentials.json

通过……进行配置 ALLOWED_PATHS 并且 BLOCKED_PATHS 环境变量。

秘密扫描

在写入任何文件之前，服务器会扫描：

AWS 密钥（AKIA...，aws_secret_key）
GitHub令牌（ghp_...，gho_...）
OpenAI API密钥（sk-...）
私钥（-----BEGIN PRIVATE KEY-----）
JWT 令牌
Slack令牌
Stripe密钥

书写者是 被阻止 如果发现秘密。

审计日志记录

所有工具调用都被记录到 logs/bridge.jsonl：

{
  "timestamp": "2025-10-12T10:30:45Z",
  "tool": "repo_write",
  "operation": "execute",
  "status": "success",
  "details": {
    "params": {"path": "src/auth.py", "mode": "overwrite"},
    "result_size": 1024
  }
}

发展

运行测试

pytest tests/

代码检查（或代码格式化）

ruff check src/ tests/

项目结构

claude-codex-mcp/
├── src/
│   ├── server.py              # MCP server entry point
│   ├── tools/
│   │   ├── repo.py           # Repository operations
│   │   ├── codex.py          # Codex CLI integration
│   │   ├── quality.py        # Linting and testing
│   │   ├── artifacts.py      # CI artifact handling
│   │   ├── git_ops.py        # Git operations
│   │   └── security.py       # Secret scanning
│   └── utils/
│       ├── config.py         # Security config
│       ├── logger.py         # Structured logging
│       └── diff_tools.py     # Diff utilities
├── examples/
│   └── demo_workflow.py      # Example workflow
└── logs/
    └── bridge.jsonl          # Audit log

常见问题解答（FAQ）

问：我需要安装Codex CLI吗？

A: 不，那个 codex_exec 工具是可选的。你可以不使用Codex而使用其他所有工具。Claude本身就能完成许多任务！

问：这会使用我的OpenAI/Codex账户吗？

A: 是的，如果你使用那个 codex_exec 工具会调用您本地安装的Codex CLI，该CLI使用您的ChatGPT/OpenAI身份验证。这会计入您的API使用量。

问：这与Codex内置的MCP服务器有何不同？

A: Codex的MCP（多合同部分/管理控制协议，具体含义根据上下文确定）暴露了Codex作为代理（黑箱委托）。这台MCP服务器为Claude提供 颗粒工具 在每一步都实现全面可见性和控制。您将获得质量检查门、安全扫描以及结构化日志记录。

问：我可以同时使用Codex的MCP和这个MCP吗？

A: 是的！配置Claude Code以使用两台服务器。Claude会根据任务选择使用哪个工具。

问：我如何自定义安全设置？

A: 编辑 .env 用于配置的文件 ALLOWED_PATHS 和 BLOCKED_PATHS你也可以修改 src/tools/security.py 添加自定义秘密图案。

做出贡献

欢迎投稿！请：

为仓库创建分支（或：克隆仓库）
创建一个特性分支
为新功能添加测试
确保代码检查通过： ruff check src/
提交一个拉取请求

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件。

致谢

建立在模型上下文协议（MCP）
受人工智能辅助开发中对精细控制需求的启发
感谢Anthropic提供的Claude代码和MCP规范