Code Executor MCP Server

代码执行器MCP

不要碰2-3MCP服务器墙。 一个MCP来协调所有这些-节省98%的代币，无限制的工具访问。

](https://www.npmjs.com/package/code-executor-mcp) ](https://hub.docker.com/r/aberemia24/code-executor-mcp) 

为什么使用代码执行器MCP？

• 代币减少98% -141k→ 1.6k个令牌（加载1个执行器vs 50多个工具）
• 沙盒安全 -隔离Deno/Python执行，默认无互联网，审计日志
• 类型安全包装 -自动生成的Types/Python SDK，具有完整的智能感知功能
• 渐进呈现 -在沙盒中按需加载工具，而不是在上下文中预先加载
• 零配置设置 -向导从Claude Code/Coursor自动检测现有的MCP服务器
• 生产就绪 -606个测试，95%以上的覆盖率，Docker支持，限速

问题

在上下文耗尽导致您死亡之前，您不能使用超过2-3个MCP服务器。

• 研究证实： 2-3台服务器后，工具精度显著下降
• 6490+可用MCP服务器，但您只能使用2-3
• 47个工具=141k个代币 在你写一个字之前就消耗掉了

你不得不选择： 文件系统或浏览器或git或AI工具。从来不是全部。

解决方案

禁用所有MCP。仅启用 code-executor-mcp.

# Before: 47 tools, 141k tokens
mcp__filesystem__read_file
mcp__filesystem__write_file
mcp__git__commit
mcp__browser__navigate
... 43 more tools

# After: 2 tools, 1.6k tokens (98% reduction)
run-typescript-code
run-python-code

沙盒内部，按需访问任何MCP工具：

// Claude writes this automatically
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 });

结果： 无限制的MCP访问，零上下文开销。

渐进式披露如何运作

sequenceDiagram
    participant C as Claude/Cursor
    participant E as Code Executor
    participant M as Other MCPs

    Note over C: ❌ Traditional: Load 50+ tools (141k tokens)

    Note over C: ✅ Code Executor: Load 2 tools (1.6k tokens)
    C->>E: run-typescript-code

    rect rgb(240, 248, 255)
        Note right of E: Sandbox (on-demand discovery)
        E->>M: callMCPTool('mcp__filesystem__read_file')
        M-->>E: Return data
    end

    E-->>C: Return result

传统的MCP预先公开了所有47个工具（141k个令牌）。Code Executor公开了2个带有outputSchema（1.6k令牌）的工具，在需要时在沙箱中按需加载其他工具。

快速开始

选项1：交互式安装向导（推荐）

不要手动配置。我们的巫师什么都会做：

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

巫师在做什么：

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

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

• AI采样：多提供商支持（Anthropic、OpenAI、Gemini、Grok、困惑）
• 安全：审核日志记录、内容过滤、项目限制
• 沙盒：Deno/Python执行超时
• 演出：速率限制、架构缓存、执行超时

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

• 端口：3333 |超时：120秒|速率限制：60/分钟
• 审核日志： ~/.code-executor/audit-logs/
• 采样：禁用（可选使用API键启用）

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

首次运行检测： 如果你试图逃跑 code-executor-mcp 无需配置：

❌ No MCP configuration found

📝 To configure code-executor-mcp, run:
   code-executor-mcp setup

Configuration will be created at: ~/.claude.json

什么是包装？

该向导为您的MCP工具生成Types/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点运行
• 视窗：任务调度程序在凌晨4-6点运行

每日同步会重新扫描您的AI工具配置和项目配置，以查找新的/删除的MCP服务器。您还可以随时手动更新 code-executor-mcp setup.

选项2：手动配置

1.安装

npm install -g code-executor-mcp

2.配置

重要： 代码执行器从以下两个位置发现并合并MCP服务器：

• 全球的： ~/.claude.json （跨项目MCP，如语音模式、个人工具）
• 项目： .mcp.json （团队在您的项目根目录中共享了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)：版本控制中的团队共享服务器
• 连接流程：克劳德代码→ 仅代码执行器，然后代码执行器→ 所有其他MCP

快速设置：

# Find Deno path
which deno
# Output: /home/user/.deno/bin/deno

# Project config (team-shared)
realpath .mcp.json
# Output: /home/user/projects/myproject/.mcp.json

# Global config (personal)
ls ~/.claude.json
# Output: /home/user/.claude.json

# Code-executor automatically merges both!

最小值（仅限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工具：

// Claude writes this when you ask to "read package.json"
const result = await callMCPTool('mcp__filesystem__read_file', {
  path: './package.json'
});
console.log(result);

就是这样。无需配置，无需配置列表，无需手动设置工具。

真实世界示例

任务： “检查auth.ts的安全问题并提交修复程序”

无代码执行器 （不可能-达到上下文限制）：

Can't enable: filesystem + git + zen codereview
Pick 2, manually do the 3rd

带代码执行器 （单个AI消息）：

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

// Review with AI
const review = await callMCPTool('mcp__zen__codereview', {
  step: 'Security audit',
  code: code,
  step_number: 1,
  total_steps: 1
});

// Apply fixes
const fixed = review.suggestions.replace(/timing-attack/g, 'constant-time');

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

// Commit
await callMCPTool('mcp__git__commit', {
  message: 'fix: constant-time token comparison'
});

console.log('Security fixes applied and committed');

一次工具调用。 变量保持不变，没有上下文切换。

特性

MCP采样（Beta）-LLM在环执行

v1.0.0中的新功能： 使Claude能够在代码执行期间调用自己进行动态推理和分析。

什么是抽样？

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

使用案例：

• 代码分析：阅读文件，让Claude分析其中的安全问题
• 多步推理：让克劳德把复杂的任务分解成步骤
• 数据处理：用克劳德的智慧处理每个文件/记录
• 交互式调试：请Claude解释错误或提出修复建议

快速示例

TypeScript：

// Enable sampling in your execution
const result = await callMCPTool('mcp__code-executor__executeTypescript', {
  code: `
    // Read a file
    const code = await callMCPTool('mcp__filesystem__read_file', {
      path: './auth.ts'
    });

    // Ask Claude to analyze it
    const analysis = await llm.ask(
      'Analyze this code for security vulnerabilities: ' + code
    );

    console.log(analysis);
  `,
  enableSampling: true,  // Enable sampling
  allowedTools: ['mcp__filesystem__read_file']
});

// Check sampling metrics
console.log('Rounds:', result.samplingMetrics.totalRounds);
console.log('Tokens:', result.samplingMetrics.totalTokens);

python

# Python example with sampling
code = """
import json

# Read data
data = call_mcp_tool('mcp__filesystem__read_file', {'path': './data.json'})

# Ask Claude to summarize
summary = await llm.ask(f'Summarize this data: {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": [
      "",
      "You are a helpful assistant",
      "You are a code analysis expert"
    ]
  }
}

混合式结构

代码执行器自动检测最佳采样方法：

1. MCP SDK采样 （免费）-如果您的MCP客户端支持 sampling/createMessage
2. 直接无烟煤API （付费）-如果MCP采样不可用，则回退（需要 ANTHROPIC_API_KEY)

⚠️ 克劳德代码限制（截至2025年11月）: 克劳德代码 不 支持MCP采样(第1785期).使用Claude Code时，采样将回退到Direct API模式（需要 ANTHROPIC_API_KEY).

兼容MCP采样的客户端:

• ✅ VS代码（v0.20.0+）
• ✅ GitHub Copilot
• ❌ 克劳德代码（待定问题#1785）

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

文档

请参阅综合采样指南： docs/sampling.md

盖子：

• 什么/为什么/如何使用架构图
• TypeScript和Python的完整API参考
• 具有威胁矩阵的安全模型
• 配置指南（环境变量、配置文件、每次执行）
• 故障排除指南（8个常见错误）
• 性能基准（\> .env

echo "CODE_EXECUTOR_AI_PROVIDER=gemini" >> .env echo "GEMINI_API_KEY=your_key_here" >> .env

3. Use wrapper script (loads .env before starting)

Update .mcp.json:

{ "code-executor": { "command": "/path/to/start-with-env.sh" } }

看 [`SAMPLING_SETUP.md`](./SAMPLING_SETUP.md) 获取完整的设置指南。

**基本用法：**

// Simple question const answer = await llm.ask('What is 2+2?'); console.log(answer); // "4"

// Multi-turn reasoning const analysis = await llm.think([ { role: 'system', content: 'You are a code reviewer' }, { role: 'user', content: 'Review this code: ...' } ]);

**高级示例-多代理代码审查：**

5个AI代理协作审查、保护、重构、测试和记录代码：

// Agent 1: Code Reviewer const review = await llm.ask('Review this code and list 5 issues...');

// Agent 2: Security Analyst const security = await llm.ask('Analyze for vulnerabilities...');

// Agent 3: Refactoring Expert const refactored = await llm.ask('Refactor using ES6+...');

// Agent 4: Test Generator const tests = await llm.ask('Generate 3 Vitest test cases...');

// Agent 5: Documentation Writer const docs = await llm.ask('Write JSDoc comments...');

**真实世界结果：**

- 5个AI代理，10秒，约2600个令牌
- 完成代码转换：审查→ 安全→ 重构→ test → 文档
- 看 [`examples/multi-agent-code-review.ts`](./examples/multi-agent-code-review.ts) 完整的工作示例

**使用案例：**

- 🤖 多代理系统（代码审查、规划、执行）
- 🔄 迭代细化（生成→ 验证→ 改善循环）
- 🧪 自主测试（生成测试、运行测试、修复故障）
- 📚 自动文档（分析代码、编写文档、验证示例）

### 多动作工作流

单个工具调用中的复杂自动化：

// Launch browser → navigate → interact → extract 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('Page title:', title); , allowedTools: ['mcp__playwright__*'] });

状态在通话中保持不变——没有上下文切换。

### Python执行（Pyodide WebAssembly）

使用Pyodide沙盒保护Python执行：

**启用Python：**

Set environment variable (REQUIRED)

export PYTHON_SANDBOX_READY=true

Enable in config

.code-executor.json

{ "executors": { "python": { "enabled": true } } }

**示例-使用MCP工具的Python：**

import asyncio

async def main(): # Discover available tools tools = await discover_mcp_tools() print(f'Found {len(tools)} tools')

# Call MCP tool to read file content = await call_mcp_tool('mcp__filesystem__read_file', { 'path': '/tmp/data.json' }) print(f'File content: {content}')

# Process data import json data = json.loads(content) result = [x * 2 for x in data['numbers']] print(f'Processed: {result}')

asyncio.run(main())

**安全保证：**

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

**限制：**

- 仅限纯Python（除非编译了WASM，否则没有本机C扩展）
- 首次加载约2-3s（Pyodide npm包），缓存\<100ms
- 无多进程/线程（使用async/await）
- 比原生Python慢10-30%（WASM开销对安全性来说是可以接受的）

看 [安全.md](SECURITY.md#-python-executor-security-pyodide) 完整的安全模型。

## 安装选项

### 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. Copy example configuration

cp docker-compose.example.yml docker-compose.yml

2. Edit docker-compose.yml to add your API keys (optional)

- Set CODE_EXECUTOR_SAMPLING_ENABLED="true"

- Set your provider: CODE_EXECUTOR_AI_PROVIDER="gemini"

- Add API key: GEMINI_API_KEY="your-key-here"

3. Start the service

docker-compose up -d

4. View logs

docker-compose logs -f

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

- ✅ 所有环境变量→ 综合配置
- ✅ 包括采样、安全、沙盒和性能设置
- ✅ 配置已保存到 `/app/config/.mcp.json`
- ✅ 持续跨容器重启（使用卷装载）

看 [医生_估计.md](DOCKER_TESTING.md) 有关安全细节和  对于所有可用的配置选项。

### 本地开发

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

## 配置

**完整示例** (`.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" } } } }

**环境变量：**
|变量|必填|描述|示例|
|----------|----------|-------------|---------|
| `MCP_CONFIG_PATH` | ⚠️ 可选|项目的显式路径 `.mcp.json` | `/home/user/projects/myproject/.mcp.json` |
| `DENO_PATH` | ✅ 对于TypeScript | Deno二进制文件的路径| `/home/user/.deno/bin/deno` |
| `ENABLE_AUDIT_LOG` | ⚠️ 建议|启用安全审核日志记录| `true` |
| `AUDIT_LOG_PATH` |否|自定义审核日志位置| `/var/log/code-executor/audit.log` |
| `ALLOWED_PROJECTS` | ⚠️ 建议|限制文件访问| `/home/user/projects:/tmp` |
| `PYTHON_ENABLED` |否|启用Python执行器| `true` （默认）|

**安全说明：** 将API密钥存储在环境变量中，而不是直接存储在配置文件中。

### 多提供商AI采样配置

**新** 支持5个AI提供商（Anthropic、OpenAI、Gemini、Grok、Perplexity），并自动选择特定于提供商的模型。

**快速设置：**

1. Copy example config

cp .env.example .env

2. Edit .env and add your API key

CODE_EXECUTOR_SAMPLING_ENABLED=true CODE_EXECUTOR_AI_PROVIDER=gemini # cheapest option! GEMINI_API_KEY=your-key-here

3. Start server

npm start

**提供商比较（2025年1月）：**
|提供者|默认模型|成本（每MTok的输入/输出）|最适合|
|----------|---------------|------------------------------|----------|
| **双子座** ⭐ | `gemini-2.5-flash-lite` | $0.10 / $0.40 | **最便宜的** +免费套餐|
|Grok| `grok-4-1-fast-non-reasoning` |0.20美元/0.50美元| 200万上下文，快速|
|OpenAI| `gpt-4o-mini` |$0.15/$0.60 |受欢迎，可靠|
|困惑| `sonar` |$1.00/$1.00 |实时搜索|
|人类学| `claude-haiku-4-5-20251001` |1.00美元/5.00美元|优质|

**配置选项：** 看 `.env.example` 有关采样配置选项的完整列表，包括：

- 所有提供程序的API密钥
- 模型满配主义者
- 利率限制和配额
- 内容过滤
- 系统提示控制

**自动发现（v0.7.3中的新功能）：** 代码执行器自动发现并合并：

- `~/.claude.json` （全球/个人MCP）
- `.mcp.json` （MCP项目）
- `MCP_CONFIG_PATH` if set（显式覆盖，仍与全局合并）

**无需配置** -只需将MCP添加到任一位置，代码执行器就会找到它们！

## 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 });

## 演出

|度量|值|
|--------|-------|
| **代币节省** |98%（141k→ 1.6k) |
| **工具发现** |\<5ms（缓存），50-100ms（首次调用）|
| **验证** |每次工具调用\<1ms|
| **沙盒启动** |约200ms（Deno），约2-3s开始/约100ms缓存（Pyodide）|
| **测试覆盖率** |606次测试，95%以上的安全性，90%以上的总体安全性|

## 文档

- [代理商.md](AGENTS.md) -AI代理的存储库指南
- [贡献.md](CONTRIBUTING.md) -开发设置和工作流程
- [安全.md](SECURITY.md) -安全模型和威胁分析
- [医生_估计.md](DOCKER_TESTING.md) -Docker安全细节
- [更改日志.md](CHANGELOG.md) -版本历史

## 常见问题解答

**Q： 我需要配置每个MCP服务器吗？**
A： 否。代码执行器会自动从以下位置发现MCP `~/.claude.json` （全球）和 `.mcp.json` （项目）。只需将MCP添加到任一位置即可。

**Q： 全局+项目配置合并是如何工作的？**
A： 代码执行器查找并合并以下两者：

- 全球(`~/.claude.json`)：个人MCP随处可用
- 项目(`.mcp.json`)：版本控制中的团队MCP
- 结果：所有MCP都可用，项目配置覆盖全局以避免重复名称

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

**Q： Python支持怎么样？**
A： 通过Pyodide WebAssembly实现完整的Python沙盒。需要 `PYTHON_SANDBOX_READY=true` 环境变量。与Deno相同的安全模型（WASM隔离、虚拟FS、网络受限）。仅限纯Python-除非编译了WASM，否则没有本机C扩展。看 [安全.md](SECURITY.md#-python-executor-security-pyodide) 了解详情。

**Q： 我可以在生产中使用这个吗？**
A： 是的。606个测试，95%以上的覆盖率，Docker支持，审计日志记录，速率限制。

**Q： 这只适用于Claude Code吗？**
A： 为克劳德代码而建。未在其他MCP客户端上测试，但应按照MCP规范工作。

## 贡献

欢迎投稿！看 [贡献.md](CONTRIBUTING.md) 作为指导方针。

**代码质量标准：**

- ✅ TypeScript严格模式
- ✅ 业务逻辑测试覆盖率超过90%
- ✅ ESLint+Pretier
- ✅ 所有PR都需要通过测试

## 许可证

麻省理工学院-参见 [许可证](LICENSE)

## 链接

- **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

______________________________________________________________________

**使用克劳德代码构建** |基于 [使用MCP执行Anthropic的代码](https://www.anthropic.com/engineering/code-execution-with-mcp)

## 星迹

[![Star History Chart](https://api.star-history.com/svg?repos=aberemia24/code-executor-MCP&type=timeline)](https://star-history.com/#aberemia24/code-executor-MCP&Timeline)