Code Executor MCP

🚀 Code Executor MCP

2 - 3つのMCPサーバーの制限を打破しましょう。 1つの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実行
• パフォーマンス: レート制限、スキーマキャッシュ、実行タイムアウト

スマートなデフォルト設定（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ツール用の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' });

ラッパーの利点:

• ✅ 完全なIntelliSense/オートコンプリートを備えた型安全なコード
• ✅ スキーマから自動生成された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は、以下の2つの場所から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

クイックセットアップ:

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

以上です。設定、許可リスト、手動のツールセットアップは不要です。

✨ 主な機能

📦 インストール

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 に保存
• ✅ コンテナの再起動時にも設定が保持される（ボリュームマウントを使用）

詳細なセキュリティ情報は DOCKER_TESTING.md を参照し、利用可能なすべての設定オプションは docker-compose.example.yml を参照してください。

ローカル開発

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

💻 使用例

基本的な使用法

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

高度な使用法

// 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');

🔧 技術詳細

問題点

コンテキストが枯渇する前に、2 - 3つ以上のMCPサーバーを使用することはできません。

• 調査による確認: 2 - 3つのサーバーを超えると、ツールの精度が大幅に低下する
• 6,490以上のMCPサーバーが利用可能 ですが、実際に使用できるのは2 - 3つだけ
• 47のツールを使用すると、コードを1文字入力する前に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つのツールのみを出力スキーマとともに公開し（1.6kトークン）、必要になったときにサンドボックス内で他のツールをロードします。

MCPサンプリング（ベータ版） - LLMを介した実行

v1.0.0での新機能: コード実行中にClaudeが自身を呼び出して、動的な推論と分析を行うことができるようになりました。

サンプリングとは？

MCPサンプリングにより、サンドボックス環境で実行されるTypeScriptおよびPythonコードが、簡単なインターフェースを通じてClaude（AnthropicのAPIを介して）を呼び出すことができます。あなたのコードは、実行中に「Claudeに助けを求める」ことができるようになります。

使用例:

• コード分析: ファイルを読み取り、Claudeにセキュリティ問題を分析させる
• 多段階推論: 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"
    ]
  }
}

ハイブリッドアーキテクチャ

Code Executorは、最適なサンプリング方法を自動的に検出します。

1. MCP SDKサンプリング（無料） - MCPクライアントが sampling/createMessage をサポートしている場合
2. 直接Anthropic API（有料） - MCPサンプリングが利用できない場合のフォールバック（ANTHROPIC_API_KEY が必要）

⚠️ Claude Codeの制限（2025年11月現在）: Claude CodeはまだMCPサンプリングをサポートしていません (Issue #1785)。Claude Codeを使用する場合、サンプリングは直接APIモードにフォールバックされます（ANTHROPIC_API_KEY が必要）。

MCPサンプリングに対応しているクライアント:

• ✅ VS Code (v0.20.0+)
• ✅ GitHub Copilot
• ❌ Claude Code (Issue #1785待ち)

Claude Codeがサンプリングサポートを追加した場合、コードの変更は必要なく、自動的に無料のMCPサンプリングに切り替わります。

ドキュメント

詳細なサンプリングガイドは docs/sampling.md を参照してください。

含まれる内容:

• アーキテクチャ図付きの概要、理由、方法
• TypeScriptとPythonの完全なAPIリファレンス
• 脅威マトリックス付きのセキュリティモデル
• 設定ガイド（環境変数、設定ファイル、実行ごとの設定）
• トラブルシューティングガイド（8つの一般的なエラー）
• パフォーマンスベンチマーク（ブリッジ起動時間<50ms）
• FAQ（15以上の質問）

セキュリティ（企業レベル）

Code Executorは単にコードを実行するだけでなく、コードを安全に保護します。

例: GitHub API以外のすべてのインターネットアクセスをブロックする設定

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

サンドボックスアーキテクチャ:

• Deno（TypeScript）: V8アイソレート、明示的なパーミッション（--allow-read=/tmp）、シェルアクセスなし
• Pyodide（Python）: WebAssemblyサンドボックス、仮想ファイルシステム、ネットワークは認証済みのMCPプロキシに制限
• Docker（オプション）: 非ルートコンテナ、読み取り専用のルート、最小限の攻撃面

詳細な脅威分析とセキュリティモデルは SECURITY.md を参照してください。

高度な使用方法

許可リスト（オプションのセキュリティ機能）

実行可能なツールを制限することができます。

await callMCPTool('mcp__code-executor__run-typescript-code', {
  code: `
    // This works
    await callMCPTool('mcp__filesystem__read_file', {...});

    // This fails - not in allowlist
    await callMCPTool('mcp__git__push', {...});
  `,
  allowedTools: ['mcp__filesystem__read_file']
});

ツールの自動検出関数

AIエージェントは、利用可能なツールを自動的に探索することができます。

// Find all tools
const tools = await discoverMCPTools();

// Search for specific functionality
const fileTools = await searchTools('file read write');

// Inspect schema
const schema = await getToolSchema('mcp__filesystem__read_file');

トークンコストはゼロ - 自動検出関数はAIエージェントのツールリストからは隠されています。

MCPサンプリング: LLMを介した実行

AIがサンドボックス化されたコード内で他のAIを自律的に呼び出して、反復的な問題解決、多エージェント協調、複雑なワークフローを実現することができます。

主要な機能:

• 複数のプロバイダーサポート: Anthropic、OpenAI、Gemini、Grok、Perplexity
• ハイブリッドモード: 自動的に有料APIにフォールバックする無料のMCPサンプリング
• シンプルなAPI: llm.ask(prompt) と llm.think(messages) ヘルパー関数
• セキュリティ: レート制限、コンテンツフィルタリング、ローカルホスト専用のブリッジ

セットアップ:

# 1. Create .env file
cp .env.example .env

# 2. Add API key
echo "CODE_EXECUTOR_SAMPLING_ENABLED=true" >> .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"
  }
}

詳細なセットアップガイドは を参照してください。

基本的な使用方法:

// 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秒、約2,600トークン
• 完全なコード変換: レビュー → セキュリティ対策 → リファクタリング → テスト → ドキュメント作成
• 完全な動作例は を参照してください。

使用例:

• 🤖 多エージェントシステム（コードレビュー、計画立案、実行）
• 🔄 反復的な改善（生成 → 検証 → 改善のループ）
• 🧪 自律的なテスト（テストの生成、実行、失敗の修正）
• 📚 自動ドキュメント作成（コードの分析、ドキュメントの作成、サンプルの検証）

多アクションワークフロー

複雑な自動化を1つのツール呼び出しで実現することができます。

// 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 - 3秒（Pyodide npmパッケージ）、キャッシュされた状態では<100ms
• マルチプロセス/スレッドは使用できません（async/awaitを使用）
• ネイティブPythonよりも10 - 30%遅い（セキュリティのためのWASMオーバーヘッドは許容範囲）

詳細なセキュリティモデルは SECURITY.md を参照してください。

📚 ドキュメント

• AGENTS.md - AIエージェントのリポジトリガイドライン
• CONTRIBUTING.md - 開発セットアップとワークフロー
• SECURITY.md - セキュリティモデルと脅威分析
• DOCKER_TESTING.md - Dockerのセキュリティ詳細
• CHANGELOG.md - バージョン履歴

📄 ライセンス

MIT - 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
• Issues: https://github.com/aberemia24/code-executor-MCP/issues

Built with Claude Code | Based on Anthropic's Code Execution with MCP

スター履歴