Code Executor MCP Server

Universal MCP server for executing TypeScript and Python code with progressive disclosure - reduces token usage by 98% compared to exposing all tools directly.

Based on Anthropic's official guide to Code Execution with MCP

⚠️ Built for Claude Code: This MCP server was developed and tested exclusively with Claude Code. While it follows MCP standards, no testing has been performed on other MCP clients (Claude Desktop, Cline, Roo, etc.). Use with other clients at your own risk.

🎯 The Problem

Tired of constantly toggling MCPs on and off in Claude Code? Need filesystem access, so you enable it. Done with that, now need zen for code review? Disable filesystem, enable zen. It's tedious and wastes context on unused tools.

With many MCP servers enabled simultaneously, you can easily hit context limits just loading tool definitions - leaving little room for actual work.

✨ The Solution: One MCP to Rule Them All

Keep ALL your MCPs disabled. Enable ONLY code-executor.

Based on Anthropic's code execution pattern, code-executor exposes up to 2 tools (executeTypescript, executePython) that can access all your other MCPs on-demand. No more toggling. No context bloat.

Progressive Disclosure: Instead of Claude directly accessing 47 tools (consuming ~150k tokens), Claude writes code that accesses those tools when needed (~1.6k tokens = 98% reduction).

Note: executeTypescript requires Deno. Without Deno, only executePython is available (still works, just Python-only).

How It Works

1. LLM calls with code + allowed tools whitelist

2. Code executes in sandbox (Deno for TypeScript, subprocess for Python)

3. Code can call to access other MCP servers

4. Results returned to LLM with audit trail

Token savings: 47 tools @ ~3,000 tokens each = 141,000 tokens saved!

🤔 When to Use This (and When NOT to)

✅ Use code-executor when you have:

• Multiple MCPs (5+) causing token bloat and context exhaustion

• Mix of local + remote tools - filesystem + Linear API + code review services

• Complex orchestration - multi-step workflows with state management

• Security requirements - need allowlisting, audit logs, rate limiting

• Existing MCP servers you want to orchestrate without rebuilding

❌ Don't use this if you only need:

• Simple filesystem operations → Use Node.js fs module or shell commands directly

• Basic git commands → Use child_process.exec('git ...')

• Single database queries → Use psql, mysql CLI directly

• One or two MCPs → Just enable them directly, no need for orchestration

Philosophy: Use the simplest tool that works. code-executor solves a specific problem: orchestrating many MCPs without context bloat. If you don't have that problem, you probably don't need this tool.

💡 Real-World Example (The Sweet Spot)

This workflow mixes local filesystem, remote AI service, Linear API (with OAuth), and Slack - all with one interface, centralized auth, and audit logging.

🚀 Features

✅ Executors

• TypeScript/JavaScript - Deno sandbox with fine-grained permissions (requires Deno)

• Python - Subprocess execution with MCP access (enabled via config)

✅ Security

• Sandbox execution - Deno for TypeScript, subprocess for Python

• Tool allowlist - Only explicitly allowed tools can be called

• Dangerous pattern detection - Blocks eval(), exec(), __import__(), pickle.loads(), etc.

• Path validation - File system access restricted to allowed projects

• Network restrictions - Default: localhost only

• Rate limiting - Token bucket algorithm (optional, 30 req/min default)

• Comprehensive audit logging - All executions logged with code hash, memory usage

✅ Configuration

• Auto-discovery - Searches .code-executor.json in project/user/XDG directories

• Environment variables - Override any setting

• Secret management - env:VAR_NAME pattern for secure config

• MCP integration - Auto-connects to all MCP servers in .mcp.json

• Safe defaults - Localhost-only network, no write access, 30s timeout

✅ Quality

• Type safe - Full TypeScript definitions, Zod validation

• Connection pooling - Limit concurrent executions (max 100)

• Error handling - Graceful degradation, clear error messages

• Well tested - 105 tests passing, 90%+ coverage

📦 Installation

Option 1: Docker (Recommended for Production)

Production-grade containerized deployment with security hardening.

Docker Security Features:

• ✅ Non-root user (UID 1001)

• ✅ Read-only root filesystem

• ✅ Resource limits (memory, CPU, PIDs)

• ✅ Network isolation (no external access by default)

• ✅ All capabilities dropped

• ✅ Custom seccomp profile (syscall filtering)

• ✅ Tini init system (zombie process reaping)

Testing Docker Security:

See DOCKER_TESTING.md for detailed testing procedures.

Option 2: NPM (Development/Local)

Running the Server

After global install:

Local development:

Link for local CLI testing:

Prerequisites

For NPM installation:

• Node.js 22.x or higher (required)

• Deno (recommended, enables TypeScript execution) - Install from deno.land

  # Quick install (Linux/macOS) curl -fsSL https://deno.land/install.sh | sh # Or use your package manager brew install deno # macOS choco install deno # Windows

• Python 3.9+ (optional, enables Python execution)

Note: Without Deno, only executePython tool will be available. TypeScript execution (executeTypescript) requires Deno.

For Docker installation:

• Docker 20.10+ and Docker Compose 2.0+

• All dependencies (Node.js, Deno, Python) are included in the image

🔧 Configuration

Docker Configuration

When running in Docker, configure via docker-compose.yml:

Note: The Docker image includes a default .mcp.json with zero servers (standalone mode). Mount your own .mcp.json to enable MCP tool access.

Local Configuration

Create .code-executor.json in your project root:

Configuration Discovery

The server searches for configuration in this order (first found wins):

1. CODE_EXECUTOR_CONFIG_PATH environment variable

2. ./.code-executor.json (project root)

3. ~/.code-executor.json (user home)

4. ~/.config/code-executor/config.json (XDG config)

Environment Variables

Override any setting with environment variables:

Secret Management

Use env:VAR_NAME pattern in configuration files to reference environment variables:

📖 Usage

Add to MCP Configuration (Claude Code)

Add to your .mcp.json (tested with Claude Code only):

MCP Transport Types

Code-executor supports two transport types for connecting to other MCP servers:

1. STDIO (Local Servers)

For local MCP servers spawned as child processes:

2. HTTP/SSE (Remote Servers)

For remote HTTP-based MCP servers (Linear, GitHub, etc.) with authentication:

How it works:

• Code-executor tries StreamableHTTP first (modern, bidirectional)

• Falls back to SSE (Server-Sent Events) if StreamableHTTP unavailable

• Supports authentication via HTTP headers (Authorization, custom headers)

Use cases:

• ✅ Linear MCP (project management via HTTP)

• ✅ GitHub MCP (repository operations via API)

• ✅ Any OAuth/token-authenticated MCP service

• ✅ Internal company MCP servers

⚠️ Important: Code-executor reads MCP servers from the project-level file (configured via mcpConfigPath in .code-executor.json). It does NOT read from user-level MCP configs like ~/.config/claude/claude_desktop_config.json. All MCP servers must be defined in your project's .mcp.json.

Authentication Flow for SSE/HTTP MCPs (Claude Code)

For SSE MCPs that require OAuth (Linear, GitHub, etc.):

1. Enable MCP - Type /mcp in Claude Code to open MCP management

2. Authenticate - Complete OAuth flow from Claude Code's MCP interface (browser will open)

3. Disable MCP - Type /mcp or @mcp and press Enter to disable the MCP in Claude Code

4. Code-executor takes over - The MCP is now authenticated and available to code-executor, but disabled in Claude Code to prevent duplicate loading

⚠️ Critical: Do NOT delete the MCP from .mcp.json - just disable it via /mcp. If you delete it, code-executor won't have access anymore. The MCP must remain in the config file (disabled state).

📝 Note: This authentication flow is for Claude Code only. The entire code-executor MCP server has been developed and tested exclusively with Claude Code. Other MCP clients have not been tested and may not work correctly.

Execute TypeScript

Execute Python (Optional)

Enable Python in config, then:

Health Check

🛠️ Creating MCP Tool Wrappers

Why We Don't Ship Wrappers

MCP servers update independently. Their APIs can change at any time without warning.

Real example:

• Zen MCP changed parameter names: cli_name → model, query → step

• Changed data types: findings: [] → findings: ''

• If we shipped wrappers, they'd be broken ❌

The solution: You create and maintain wrappers that match YOUR installed MCP server versions.

Copy-Paste Templates

We provide battle-tested templates instead of shipped code:

Available Templates

• docs/examples/zen-wrapper-template.ts - AI analysis tools (thinkdeep, codereview, etc.)

• docs/examples/filesystem-wrapper-template.ts - File operations (read, write, search)

• docs/examples/CREATING_WRAPPERS.md - Complete guide for creating your own

Benefits of This Approach

✅ Your wrappers match YOUR MCP server versions ✅ You update when YOU update MCP servers ✅ No dependency on our release schedule ✅ No "broken package" issues ✅ Full TypeScript autocomplete in your IDE

Quick Start

1. Copy template:

2. Adapt to your environment:

3. Use throughout your project:

See

🔒 Security Model

Multi-Layer Defense Strategy

Code-executor implements defense-in-depth with multiple security layers:

1. Path Traversal Protection (CWE-22)

   • Symlink resolution with fs.realpath()

   • Canonical path validation before access

   • Prevents directory escape attacks

2. SSRF Protection (CWE-918)

   • Comprehensive IP blocklist (localhost, RFC 1918 private networks)

   • Cloud metadata endpoint filtering (AWS, GCP, Azure)

   • Hostname and resolved IP validation

3. HTTP Proxy Authentication (CWE-306)

   • Cryptographically secure bearer tokens (32 bytes)

   • All sandbox-to-MCP communication authenticated

   • Prevents unauthorized tool access

4. Temp File Integrity (CWE-345)

   • SHA-256 hash verification after write

   • Detects tampering before execution

   • Race condition prevention

5. Container Isolation (Docker)

   • Non-root user execution (UID 1001)

   • Read-only root filesystem

   • Network isolation (no external access)

   • Resource limits (memory, CPU, PIDs)

   • Syscall filtering (seccomp profile)

Principle of Least Privilege

1. Default: Deny All - No file system or network access by default

2. Explicit Allowlist - Each execution specifies allowed tools

3. Path Validation - File paths must be within allowRead/allowWrite

4. Pattern Detection - Dangerous code patterns blocked before execution

5. Sandbox Isolation - Deno/subprocess provide OS-level isolation

6. Rate Limiting - Token bucket algorithm prevents abuse

Dangerous Patterns Blocked

JavaScript/TypeScript:

• eval(), Function(), new Function(), .constructor.constructor()

• require(), import() (dynamic imports)

• child_process, Deno.run, Deno.Command

• setTimeout('code'), setInterval('code')

Python:

• exec(), __import__(), compile()

• pickle.loads() (deserialization RCE)

• os.system(), subprocess.run/call/Popen

• globals(), locals(), __builtins__

• open(..., 'w') (write mode)

Audit Logging

All executions are logged with:

• Timestamp (ISO 8601)

• Executor type (typescript/python)

• Code hash (SHA-256)

• Code length (bytes)

• Allowed tools (whitelist)

• Tools called (actual usage)

• Execution time (milliseconds)

• Memory usage (bytes)

• Success/error status

• Client identifier (for rate limiting)

Example audit log entry:

Rate Limiting

Optional token bucket rate limiter:

Features:

• Token bucket algorithm - Smooth limiting with burst capacity

• Per-client limiting - Default: single "default" client (MCP servers run locally)

• Automatic cleanup - Stale buckets removed every 5 minutes

• Graceful errors - Clear messages with retry timing

📊 Architecture

🚀 Production Deployment

Docker Deployment (Recommended)

1. Build Production Image

2. Deploy with Docker Compose

3. Security Checklist

• ✅ Run as non-root (UID 1001)

• ✅ Enable read-only filesystem

• ✅ Set resource limits (512MB RAM, 0.5 CPU)

• ✅ Drop all capabilities

• ✅ Use seccomp profile

• ✅ Network isolation (default)

• ✅ Mount projects read-only

• ✅ Enable audit logging

4. Health Monitoring

Production Configuration

🧪 Development

Setup

Commands

Testing

Current Status: ✅ 105 tests passing | ✅ 90%+ coverage | ✅ Clean TypeScript build

📈 Progressive Disclosure Pattern

Traditional Approach (❌ ~150,000 tokens)

• Load all 47 MCP tool definitions upfront

• Wasted context on unused tools

• Tools: 47 × ~3,000 tokens = ~141,000 tokens

• Overhead: ~9,000 tokens (descriptions, schemas)

• Total: ~150,000 tokens

Progressive Disclosure (✅ ~1,600 tokens)

• Load only 2-3 code-executor tool definitions

• Tools loaded on-demand via callMCPTool()

• Tools: 2-3 × ~500 tokens = ~1,000-1,500 tokens

• Overhead: ~100 tokens

• Total: ~1,600 tokens

Savings: 98% reduction (148,400 tokens saved!)

Real-World Example

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

Code Quality Standards

• ✅ TypeScript strict mode

• ✅ 90%+ test coverage on business logic

• ✅ All tests passing

• ✅ ESLint + Prettier

• ✅ Meaningful commit messages

📄 License

MIT License - see LICENSE for details.

🔐 Security

Current Security Status:

• ✅ Path traversal protection (symlink resolution)

• ✅ SSRF mitigation (IP blocklist)

• ✅ HTTP proxy authentication (bearer tokens)

• ✅ Temp file integrity (SHA-256 verification)

• ✅ Docker containerization (multi-layer isolation)

• ✅ Comprehensive audit logging

Found a security vulnerability? See SECURITY.md for:

• Documented vulnerabilities and mitigations

• Responsible disclosure process

• Security audit history

Please do not open public issues for security vulnerabilities.

Testing Security:

🙏 Acknowledgments

• Model Context Protocol (MCP) - Anthropic's standard for LLM-tool communication

• Deno - Secure TypeScript runtime with fine-grained permissions

• Progressive Disclosure Pattern - UI/UX principles applied to LLM context management

📚 Related

MCP & Code Execution:

• MCP Specification

• Claude Code Documentation

• Anthropic's Code Execution Guide

• Deno Documentation

Security:

• OWASP Top 10

• CWE-22: Path Traversal

• CWE-918: SSRF

• Docker Security Best Practices

• Seccomp Security Profiles

Algorithms & Patterns:

• Token Bucket Algorithm

• Progressive Disclosure (UX)

Project Documentation:

• SECURITY.md - Vulnerability documentation and mitigations

• DOCKER_TESTING.md - Docker security testing procedures

• CLAUDE.md - AI assistant context and standards

**Made with ❤️ for anyone really. this has always been a pain point. i am sure that anthropic will release an official something for this, until then, hope this helps.