Code Executor MCP

🚀 Code Executor MCP

Code Executor MCP 打破了只能使用 2 - 3 个 MCP 服务器的限制。它凭借单一的 MCP 便能统筹全局，实现高达 98% 的令牌节省，让你无需担忧上下文耗尽的问题，可无限制地访问各类工具。

🚀 快速开始

选项 1：交互式设置向导（推荐）

无需手动配置，我们的向导将为你完成一切：

npm install -g code-executor-mcp
code-executor-mcp setup

向导的功能如下：

1. 🔍 扫描现有的 MCP 配置（Claude Code 的 ~/.claude.json、Cursor 的 ~/.cursor/mcp.json 以及项目的 .mcp.json）
2. ⚙️ 使用智能默认值进行配置（也可交互式自定义）
3. 🤖 新增功能：写入完整的 MCP 配置（采样 + 安全 + 沙箱 + 性能）
4. 📦 生成类型安全的 TypeScript/Python 包装器，以实现自动补全
5. 📅 可选：设置每日同步，以自动更新包装器

完整配置（全部自动写入）：

• AI 采样：支持多供应商（Anthropic、OpenAI、Gemini、Grok、Perplexity）
• 安全：审计日志、内容过滤、项目限制
• 沙箱：带有超时设置的 Deno/Python 执行环境
• 性能：速率限制、模式缓存、执行超时

智能默认值（只需按回车键）：

• 端口：3333 | 超时时间：120 秒 | 速率限制：60 次/分钟
• 审计日志：~/.code-executor/audit-logs/
• 采样：禁用（可通过 API 密钥可选启用）

支持的 AI 工具：Claude Code 和 Cursor（更多即将推出）

首次运行检测： 如果你在未配置的情况下尝试运行 code-executor-mcp，将会看到以下提示：

❌ 未找到 MCP 配置

📝 要配置 code-executor-mcp，请运行：
   code-executor-mcp setup

配置将创建于：~/.claude.json

什么是包装器？

向导会为你的 MCP 工具生成 TypeScript/Python 包装器函数：

手动调用（之前）：

const file = await callMCPTool('mcp__filesystem__read_file', {
  path: '/src/app.ts'
});

使用包装器（之后）：

import { filesystem } from './mcp-wrappers';
const file = await filesystem.readFile({ path: '/src/app.ts' });

好处：

• ✅ 类型安全，具备完整的智能感知/自动补全功能
• ✅ 带有来自模式的自文档化 JSDoc 注释
• ✅ 无需记住确切的工具名称
• ✅ 与实际的 MCP 工具 API 相匹配（从模式生成）

保持包装器更新： 向导可以设置每日同步（可选），以自动重新生成包装器：

• macOS：launchd plist 在凌晨 4 - 6 点运行
• Linux：systemd 定时器在凌晨 4 - 6 点运行
• Windows：任务计划程序在凌晨 4 - 6 点运行

每日同步会重新扫描你的 AI 工具配置和项目配置，以发现新的或已移除的 MCP 服务器。你也可以随时手动运行 code-executor-mcp setup 进行更新。

选项 2：手动配置

1. 安装

npm install -g code-executor-mcp

2. 配置

重要提示：Code-executor 会从以下两个位置发现并合并 MCP 服务器：

• 全局：~/.claude.json（跨项目的 MCP，如语音模式、个人工具）
• 项目：.mcp.json（项目根目录下团队共享的 MCP）

配置合并规则：全局 MCP + 项目 MCP = 所有可用的 MCP（项目配置会覆盖全局配置中重复的名称）

将以下内容添加到你的 项目 .mcp.json 或 全局 ~/.claude.json 中：

{
  "mcpServers": {
    "code-executor": {
      "command": "npx",
      "args": ["-y", "code-executor-mcp"],
      "env": {
        "MCP_CONFIG_PATH": "/full/path/to/this/.mcp.json",
        "DENO_PATH": "/path/to/.deno/bin/deno"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"]
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp", "--headless"]
    }
  }
}

配置指南：

• MCP_CONFIG_PATH：可选 - 指向项目 .mcp.json（仍会发现全局 ~/.claude.json）
• DENO_PATH：运行 which deno 以查找其路径（TypeScript 执行所需）
• 全局 MCP (~/.claude.json)：可在所有项目中使用的个人服务器
• 项目 MCP (.mcp.json)：版本控制中团队共享的服务器
• 连接流程：Claude Code → 仅 code-executor，然后 code-executor → 所有其他 MCP

快速设置：

# 查找 Deno 路径
which deno
# 输出：/home/user/.deno/bin/deno

# 项目配置（团队共享）
realpath .mcp.json
# 输出：/home/user/projects/myproject/.mcp.json

# 全局配置（个人）
ls ~/.claude.json
# 输出：/home/user/.claude.json

# Code-executor 会自动合并两者！

最小配置（仅 Python）：

{
  "mcpServers": {
    "code-executor": {
      "command": "npx",
      "args": ["-y", "code-executor-mcp"],
      "env": {
        "MCP_CONFIG_PATH": "/path/to/.mcp.json",
        "PYTHON_ENABLED": "true"
      }
    }
  }
}

3. 使用

Claude 现在可以通过代码执行访问任何 MCP 工具：

// 当你要求 "读取 package.json" 时，Claude 会自动生成此代码
const result = await callMCPTool('mcp__filesystem__read_file', {
  path: './package.json'
});
console.log(result);

就是这么简单，无需配置、无需白名单、无需手动设置工具。

✨ 主要特性

📦 安装指南

npm（推荐）

npm install -g code-executor-mcp
code-executor-mcp

Docker（生产环境）

快速开始：

docker pull aberemia24/code-executor-mcp:latest
docker run -p 3333:3333 aberemia24/code-executor-mcp:latest

使用 docker-compose（推荐）：

# 1. 复制示例配置
cp docker-compose.example.yml docker-compose.yml

# 2. 编辑 docker-compose.yml 以添加你的 API 密钥（可选）
#    - 设置 CODE_EXECUTOR_SAMPLING_ENABLED="true"
#    - 设置你的供应商：CODE_EXECUTOR_AI_PROVIDER="gemini"
#    - 添加 API 密钥：GEMINI_API_KEY="your-key-here"

# 3. 启动服务
docker-compose up -d

# 4. 查看日志
docker-compose logs -f

首次运行自动配置： Docker 部署会在首次运行时根据环境变量自动生成完整的 MCP 配置：

• ✅ 所有环境变量 → 全面的配置
• ✅ 包括采样、安全、沙箱和性能设置
• ✅ 配置保存到 /app/config/.mcp.json
• ✅ 在容器重启时保持持久化（使用卷挂载）

本地开发

git clone https://github.com/aberemia24/code-executor-MCP.git
cd code-executor-mcp
npm install && npm run build
npm run server

💻 使用示例

基础用法

# 之前：47 个工具，141k 个令牌
mcp__filesystem__read_file
mcp__filesystem__write_file
mcp__git__commit
mcp__browser__navigate
... 还有 43 个工具

# 之后：2 个工具，1.6k 个令牌（节省 98%）
run-typescript-code
run-python-code

高级用法

// Claude 会自动生成此代码
const file = await callMCPTool('mcp__filesystem__read_file', { path: '/src/app.ts' });
const review = await callMCPTool('mcp__zen__codereview', { code: file });
await callMCPTool('mcp__git__commit', { message: review.suggestions });

实际示例

任务：“审查 auth.ts 文件的安全问题并提交修复”

没有 code-executor 的情况（不可能完成 - 达到上下文限制）：

无法同时启用：文件系统 + Git + Zen 代码审查
只能选择 2 个，手动完成第 3 个

使用 code-executor 的情况（单个 AI 消息）：

// 读取文件
const code = await callMCPTool('mcp__filesystem__read_file', {
  path: '/src/auth.ts'
});

// 使用 AI 进行审查
const review = await callMCPTool('mcp__zen__codereview', {
  step: '安全审计',
  code: code,
  step_number: 1,
  total_steps: 1
});

// 应用修复
const fixed = review.suggestions.replace(/timing-attack/g, 'constant-time');

await callMCPTool('mcp__filesystem__write_file', {
  path: '/src/auth.ts',
  content: fixed
});

// 提交更改
await callMCPTool('mcp__git__commit', {
  message: 'fix: 常量时间令牌比较'
});

console.log('安全修复已应用并提交');

所有操作只需一次工具调用。变量会持续存在，无需上下文切换。

📚 详细文档

MCP 采样（Beta） - 循环内大语言模型执行

v1.0.0 新增功能：允许 Claude 在代码执行期间调用自身，以进行动态推理和分析。

什么是采样？

MCP 采样允许在沙箱环境中运行的 TypeScript 和 Python 代码通过简单的接口调用 Claude（通过 Anthropic 的 API）。现在，你的代码可以在执行过程中“向 Claude 寻求帮助”。

用例：

• 代码分析：读取文件，让 Claude 分析其安全问题
• 多步骤推理：让 Claude 将复杂任务分解为多个步骤
• 数据处理：使用 Claude 的智能处理每个文件/记录
• 交互式调试：让 Claude 解释错误或提供修复建议

快速示例

TypeScript：

// 在执行中启用采样
const result = await callMCPTool('mcp__code-executor__executeTypescript', {
  code: `
    // 读取文件
    const code = await callMCPTool('mcp__filesystem__read_file', {
      path: './auth.ts'
    });

    // 让 Claude 进行分析
    const analysis = await llm.ask(
      '分析此代码的安全漏洞：' + code
    );

    console.log(analysis);
  `,
  enableSampling: true,  // 启用采样
  allowedTools: ['mcp__filesystem__read_file']
});

// 检查采样指标
console.log('轮数:', result.samplingMetrics.totalRounds);
console.log('令牌数:', result.samplingMetrics.totalTokens);

Python：

# 带有采样的 Python 示例

code = """
import json

# 读取数据
data = call_mcp_tool('mcp__filesystem__read_file', {'path': './data.json'})

# 让 Claude 进行总结
summary = await llm.ask(f'总结此数据：{data}')

print(summary)
"""

result = call_mcp_tool('mcp__code-executor__executePython', {
    'code': code,
    'enableSampling': True
})

API 参考

TypeScript API：

• llm.ask(prompt: string, options?) - 简单查询，返回响应文本
• llm.think({messages, model?, maxTokens?, systemPrompt?}) - 多轮对话

Python API：

• llm.ask(prompt: str, system_prompt='', max_tokens=1000) - 简单查询
• llm.think(messages, model='', max_tokens=1000, system_prompt='') - 多轮对话

安全控制

采样包含企业级安全控制：

配置

启用采样：

选项 1 - 每次执行（推荐）：

{ enableSampling: true }

选项 2 - 环境变量：

export CODE_EXECUTOR_SAMPLING_ENABLED=true
export CODE_EXECUTOR_MAX_SAMPLING_ROUNDS=10
export CODE_EXECUTOR_MAX_SAMPLING_TOKENS=10000

选项 3 - 配置文件 (~/.code-executor/config.json)：

{
  "sampling": {
    "enabled": true,
    "maxRoundsPerExecution": 10,
    "maxTokensPerExecution": 10000,
    "allowedSystemPrompts": [
      "",
      "你是一个有用的助手",
      "你是一位代码分析专家"
    ]
  }
}

混合架构

Code Executor 会自动检测最佳采样方法：

1. MCP SDK 采样（免费） - 如果你的 MCP 客户端支持 sampling/createMessage
2. 直接 Anthropic API（付费） - 如果 MCP 采样不可用，则回退到此模式（需要 ANTHROPIC_API_KEY）

⚠️ Claude Code 限制（截至 2025 年 11 月）： Claude Code 目前 不支持 MCP 采样（问题 #1785）。使用 Claude Code 时，采样将回退到直接 API 模式（需要 ANTHROPIC_API_KEY）。

支持 MCP 采样的兼容客户端：

• ✅ VS Code（v0.20.0+）
• ✅ GitHub Copilot
• ❌ Claude Code（待解决问题 #1785）

当 Claude Code 增加采样支持时，无需更改代码 - 它将自动切换到免费的 MCP 采样。

文档

请参阅全面的采样指南：docs/sampling.md

涵盖内容：

• 架构图解释采样的原理、原因和方法
• TypeScript 和 Python 的完整 API 参考
• 带有威胁矩阵的安全模型
• 配置指南（环境变量、配置文件、每次执行）
• 故障排除指南（8 个常见错误）
• 性能基准测试（桥接启动时间 <50ms）
• 常见问题解答（15 个以上问题）

配置

完整示例 (.mcp.json)：

{
  "mcpServers": {
    "code-executor": {
      "command": "npx",
      "args": ["-y", "code-executor-mcp"],
      "env": {
        "MCP_CONFIG_PATH": "/absolute/path/to/.mcp.json",
        "DENO_PATH": "/home/user/.deno/bin/deno",
        "ENABLE_AUDIT_LOG": "true",
        "AUDIT_LOG_PATH": "/home/user/.code-executor/audit.log",
        "ALLOWED_PROJECTS": "/home/user/projects:/tmp"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"]
    },
    "zen": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/zen-mcp.git", "zen-mcp-server"],
      "env": {
        "GEMINI_API_KEY": "your-key-here"
      }
    }
  }
}

环境变量：

安全注意事项：将 API 密钥存储在环境变量中，而不是直接存储在配置文件中。

多供应商 AI 采样配置

新增功能：支持 5 个 AI 供应商（Anthropic、OpenAI、Gemini、Grok、Perplexity），并自动选择特定供应商的模型。

快速设置：

# 1. 复制示例配置
cp .env.example .env

# 2. 编辑 .env 文件并添加你的 API 密钥
CODE_EXECUTOR_SAMPLING_ENABLED=true
CODE_EXECUTOR_AI_PROVIDER=gemini  # 最便宜的选项！
GEMINI_API_KEY=your-key-here

# 3. 启动服务器
npm start

供应商比较（2025 年 1 月）：

配置选项：请参阅 .env.example 以获取完整的采样配置选项列表，包括：

• 所有供应商的 API 密钥
• 模型白名单
• 速率限制和配额
• 内容过滤
• 系统提示控制

自动发现（v0.7.3 新增功能）：Code-executor 会自动发现并合并：

• ~/.claude.json（全局/个人 MCP）
• .mcp.json（项目 MCP）
• MCP_CONFIG_PATH（如果设置）（显式覆盖，但仍会与全局配置合并）

无需配置 - 只需将 MCP 添加到任一位置，code-executor 就会找到它们！

🔧 技术细节

TypeScript 支持

包含完整的类型定义：

import { MCPClientPool, executeTypescript, type ToolSchema } from 'code-executor-mcp';

const pool = new MCPClientPool();
await pool.initialize('/path/to/.mcp.json');

const result = await executeTypescript({
  code: `const tools = await discoverMCPTools(); console.log(tools.length);`,
  allowedTools: ['mcp__*'],
  timeoutMs: 30000
});

性能

安全（企业级）

Code Executor 不仅能“运行代码”，还能保障代码安全：

示例：除 GitHub API 外，阻止所有网络访问：

{
  "security": {
    "allowedDomains": ["api.github.com"],
    "allowedProjects": ["/home/user/projects"]
  }
}

沙箱架构：

• Deno（TypeScript）：V8 隔离环境，具有显式权限（--allow-read=/tmp），无 shell 访问权限
• Pyodide（Python）：WebAssembly 沙箱，虚拟文件系统，网络访问仅限于经过身份验证的 MCP 代理
• Docker（可选）：非根容器，只读根文件系统，最小化攻击面

请参阅 SECURITY.md 以获取完整的威胁分析和安全模型。

高级用法

白名单（可选安全措施）

限制可执行的工具：

await callMCPTool('mcp__code-executor__run-typescript-code', {
  code: `
    // 此操作可行
    await callMCPTool('mcp__filesystem__read_file', {...});

    // 此操作失败 - 不在白名单中
    await callMCPTool('mcp__git__push', {...});
  `,
  allowedTools: ['mcp__filesystem__read_file']
});

发现功能

AI 代理可以按需探索可用工具：

// 查找所有工具
const tools = await discoverMCPTools();

// 搜索特定功能
const fileTools = await searchTools('文件读写');

// 检查模式
const schema = await getToolSchema('mcp__filesystem__read_file');

零令牌成本 - 发现功能不会显示在 AI 代理的工具列表中。

MCP 采样：循环内大语言模型执行

允许 AI 在沙箱代码中自主调用其他 AI，以实现迭代问题解决、多智能体协作和复杂工作流。

关键特性：

• 多供应商支持：Anthropic、OpenAI、Gemini、Grok、Perplexity
• 混合模式：免费的 MCP 采样，自动回退到付费 API
• 简单 API：llm.ask(prompt) 和 llm.think(messages) 辅助函数
• 安全保障：速率限制、内容过滤、仅本地访问的桥接服务器

设置：

# 1. 创建 .env 文件
cp .env.example .env

# 2. 添加 API 密钥
echo "CODE_EXECUTOR_SAMPLING_ENABLED=true" >> .env
echo "CODE_EXECUTOR_AI_PROVIDER=gemini" >> .env
echo "GEMINI_API_KEY=your_key_here" >> .env

# 3. 使用包装脚本（在启动前加载 .env）
# 更新 .mcp.json：
{
  "code-executor": {
    "command": "/path/to/start-with-env.sh"
  }
}

请参阅 以获取完整的设置指南。

基本用法：

// 简单问题
const answer = await llm.ask('2 + 2 等于多少？');
console.log(answer); // "4"

// 多轮推理
const analysis = await llm.think([
  { role: 'system', content: '你是一名代码审查员' },
  { role: 'user', content: '审查这段代码：...' }
]);

高级示例 - 多智能体代码审查： 5 个 AI 智能体协作审查、保障安全、重构、测试和文档化代码：

// 智能体 1：代码审查员
const review = await llm.ask('审查这段代码并列出 5 个问题...');

// 智能体 2：安全分析师
const security = await llm.ask('分析安全漏洞...');

// 智能体 3：重构专家
const refactored = await llm.ask('使用 ES6+ 进行重构...');

// 智能体 4：测试生成器
const tests = await llm.ask('生成 3 个 Vitest 测试用例...');

// 智能体 5：文档编写员
const docs = await llm.ask('编写 JSDoc 注释...');

实际结果：

• 5 个 AI 智能体，10 秒，约 2600 个令牌
• 完整的代码转换：审查 → 保障安全 → 重构 → 测试 → 文档化
• 请参阅 以获取完整的工作示例

用例：

• 🤖 多智能体系统（代码审查、规划、执行）
• 🔄 迭代优化（生成 → 验证 → 改进循环）
• 🧪 自主测试（生成测试用例、运行测试、修复失败）
• 📚 自动文档化（分析代码、编写文档、验证示例）

多动作工作流

在一次工具调用中实现复杂的自动化：

// 启动浏览器 → 导航 → 交互 → 提取数据
await callMCPTool('mcp__code-executor__run-typescript-code', {
  code: `
    await callMCPTool('mcp__playwright__launch', { headless: false });
    await callMCPTool('mcp__playwright__navigate', { url: 'https://example.com' });
    const title = await callMCPTool('mcp__playwright__evaluate', {
      script: 'document.title'
    });
    console.log('页面标题:', title);
  `,
  allowedTools: ['mcp__playwright__*']
});

状态在调用之间保持持久 - 无需上下文切换。

Python 执行（Pyodide WebAssembly）

使用 Pyodide 沙箱实现安全的 Python 执行：

启用 Python：

# 设置环境变量（必需）
export PYTHON_SANDBOX_READY=true

# 在配置中启用
# .code-executor.json
{
  "executors": {
    "python": {
      "enabled": true
    }
  }
}

示例 - 使用 MCP 工具的 Python 代码：

import asyncio

async def main():
    # 发现可用工具
    tools = await discover_mcp_tools()
    print(f'找到 {len(tools)} 个工具')

    # 调用 MCP 工具读取文件
    content = await call_mcp_tool('mcp__filesystem__read_file', {
        'path': '/tmp/data.json'
    })
    print(f'文件内容: {content}')

    # 处理数据
    import json
    data = json.loads(content)
    result = [x * 2 for x in data['numbers']]
    print(f'处理结果: {result}')

asyncio.run(main())

安全保障：

• ✅ WebAssembly 沙箱（与 Deno 具有相同的安全性）
• ✅ 虚拟文件系统（无主机文件访问）
• ✅ 网络访问仅限于经过身份验证的 MCP 代理
• ✅ 无子进程生成
• ✅ 内存受 V8 堆限制

限制：

• 仅支持纯 Python（除非经过 WASM 编译，否则不支持原生 C 扩展）
• 首次加载约 2 - 3 秒（Pyodide npm 包），缓存后 <100ms
• 不支持多进程/线程（使用 async/await）
• 比原生 Python 慢 10 - 30%（为了安全，WASM 开销可以接受）

请参阅 SECURITY.md 以获取完整的安全模型。

📄 许可证

本项目采用 MIT 许可证，请参阅 LICENSE 了解详细信息。

常见问题解答

Q：是否需要为每个 MCP 服务器进行配置？ A：不需要。Code-executor 会自动从 ~/.claude.json（全局）和 .mcp.json（项目）中发现 MCP。只需将 MCP 添加到任一位置即可。

Q：全局配置和项目配置如何合并？ A：Code-executor 会找到并合并两者：

• 全局 (~/.claude.json)：可在所有项目中使用的个人 MCP
• 项目 (.mcp.json)：版本控制中团队共享的 MCP
• 结果：所有 MCP 都可用，项目配置会覆盖全局配置中重复的名称

Q：验证是如何工作的？ A：AJV 会根据实时模式验证所有工具调用。发生错误时，你会收到一条详细的消息，显示预期的参数。

Q：Python 支持情况如何？ A：通过 Pyodide WebAssembly 提供完整的 Python 沙箱。需要设置 PYTHON_SANDBOX_READY=true 环境变量。与 Deno 具有相同的安全模型（WASM 隔离、虚拟文件系统、网络受限）。仅支持纯 Python - 除非经过 WASM 编译，否则不支持原生 C 扩展。请参阅 SECURITY.md 了解详细信息。

Q：是否可以在生产环境中使用？ A：可以。有 606 个测试用例，覆盖率达 95% 以上，支持 Docker，有审计日志和速率限制。

Q：它是否仅适用于 Claude Code？ A：它是为 Claude Code 构建的。虽然未在其他 MCP 客户端上进行测试，但根据 MCP 规范应该可以正常工作。

贡献

欢迎贡献代码！请参阅 CONTRIBUTING.md 了解贡献指南。

代码质量标准：

• ✅ TypeScript 严格模式
• ✅ 业务逻辑的测试覆盖率达 90% 以上
• ✅ ESLint + Prettier
• ✅ 所有拉取请求都必须通过测试

链接

• npm：https://www.npmjs.com/package/code-executor-mcp
• Docker Hub：https://hub.docker.com/r/aberemia24/code-executor-mcp
• GitHub：https://github.com/aberemia24/code-executor-MCP
• 问题反馈：https://github.com/aberemia24/code-executor-MCP/issues

使用 Claude Code 构建 | 基于 Anthropic 的 MCP 代码执行

星标历史