MCP Executor Server

A secure, Docker-based code execution server that provides HTTP API endpoints for running Python code in isolated containers. Perfect for integration with automation tools like n8n, web applications, or any HTTP client.

🚀 Features

🔒 Secure Execution - Code runs in isolated Docker containers
⚡ Fast Performance - Optimized for quick code execution
📡 Real-time Streaming - Server-Sent Events (SSE) for live output
🌐 HTTP API - RESTful endpoints for easy integration
📊 Health Monitoring - Built-in health check endpoint
🐍 Python Support - Execute Python code with full library access
🔧 Docker Integration - Uses my-llm-sandbox container for execution

📋 Prerequisites

Docker Desktop - Must be running and in Linux containers mode
Node.js - Version 18+ recommended
Docker Image - my-llm-sandbox image must be available locally

🛠️ Installation & Setup

1. Clone and Navigate

cd src

2. Install Dependencies

npm install

3. Start the Server

Development Mode (Recommended):

npm run dev

Production Mode:

npm run build
npm start

The server will start on http://localhost:3000

📡 API Endpoints

1. Execute Code

POST /execute

Execute Python code in a secure Docker container.

Request Body:

{
  "code": "print('Hello, World!')",
  "language": "python",
  "timeout": 30,
  "libraries": []
}

Response:

{
  "content": [
    {
      "type": "text",
      "text": "Hello, World!\n"
    }
  ],
  "exitCode": 0
}

2. Real-time Streaming

GET /sse

Connect to Server-Sent Events for real-time output streaming.

Usage:

Open in browser: http://localhost:3000/sse
Or use curl: curl http://localhost:3000/sse

Output Format:

data: {"type":"stdout","data":"Hello, World!\n"}
data: {"type":"stderr","data":"Error message\n"}

3. Health Check

GET /health

Check if the server is running properly.

Response:

{
  "status": "ok",
  "message": "MCP Executor server is healthy",
  "timestamp": "2025-07-10T18:12:11.711Z"
}

🧪 Testing

Using Postman

Test Health Check:
- Method: GET
- URL: http://localhost:3000/health
Test Code Execution:
- Method: POST
- URL: http://localhost:3000/execute
- Headers: Content-Type: application/json
- Body:
{ "code": "print('Hello from Postman!')", "language": "python" }
Test SSE Streaming:
- Method: GET
- URL: http://localhost:3000/sse
- Keep connection open while testing /execute

Using curl

# Health check
curl http://localhost:3000/health

# Execute code
curl -X POST http://localhost:3000/execute \
  -H "Content-Type: application/json" \
  -d '{"code": "print(\"Hello from curl!\")", "language": "python"}'

# SSE streaming
curl http://localhost:3000/sse

🔧 n8n Integration

Basic Setup

Add HTTP Request Node
Configure:
- Method: POST
- URL: http://localhost:3000/execute
- Headers: Content-Type: application/json
- Body (JSON):
{ "code": "print('Hello from n8n!')", "language": "python" }

Advanced Examples

Dynamic Code Execution:

{
  "code": "{{ $json.code }}",
  "language": "python"
}

Data Processing:

{
  "code": "import json; data = {{ $json.data }}; print('Processed:', len(data))",
  "language": "python"
}

File Operations:

{
  "code": "with open('output.txt', 'w') as f: f.write('{{ $json.content }}'); print('File written')",
  "language": "python"
}

📁 Project Structure

src/
├── index.ts          # Main Express server
├── server.ts         # Docker execution logic
├── utils/
│   └── sse.ts       # Server-Sent Events handling
├── types/            # TypeScript type definitions
├── tools/            # Tool definitions
├── docs/             # Documentation
├── package.json      # Dependencies and scripts
├── tsconfig.json     # TypeScript configuration
├── Dockerfile        # Docker configuration
└── README.md         # This file

🔍 Troubleshooting

Common Issues

Docker not running:
- Ensure Docker Desktop is running
- Check that it's in Linux containers mode
Container not found:
- Verify my-llm-sandbox image exists: docker images
- Rebuild if needed: docker build -t my-llm-sandbox .
Permission denied:
- Ensure Docker has proper permissions
- Check Docker socket access
Slow responses:
- First request may take 2-3 seconds (container startup)
- Subsequent requests should be fast (1-2 seconds)

Debug Mode

Enable detailed logging by checking the server console output for:

[STDOUT] - Docker container output
[STDERR] - Docker container errors
Executing code in Docker container... - Request processing

🚀 Deployment

Docker Deployment

Build the image:
docker build -t mcp-executor .
Run the container:
docker run -p 3000:3000 -v /var/run/docker.sock:/var/run/docker.sock mcp-executor

Environment Variables

PORT - Server port (default: 3000)
NODE_ENV - Environment (development/production)

📝 Examples

Simple Python Code

{
  "code": "print('Hello, World!')",
  "language": "python"
}

Mathematical Operations

{
  "code": "import math; print(f'Pi: {math.pi}'); print(f'2^10: {2**10}')",
  "language": "python"
}

Data Processing

{
  "code": "data = [1, 2, 3, 4, 5]; print(f'Sum: {sum(data)}'); print(f'Average: {sum(data)/len(data)}')",
  "language": "python"
}

File Operations

{
  "code": "with open('test.txt', 'w') as f: f.write('Hello from Docker!'); print('File created')",
  "language": "python"
}

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Test thoroughly
Submit a pull request

📄 License

This project is licensed under the ISC License.

🆘 Support

For issues and questions:

Check the troubleshooting section
Review the console logs
Test with simple code examples
Verify Docker setup

Happy coding! 🎉

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

A secure server that enables code execution in isolated Docker environments, supporting Python with strict security constraints including network isolation, limited filesystem access, and resource limitations.

Related MCP Servers

Sandbox MCP Server
Tsuchijo
-
security
F
license
-
quality
Provides isolated Docker environments for code execution, enabling users to create and manage containers, execute multi-language code, save and reproduce development environments, ensuring security and isolation.
Last updated -
10
Python
Docker MCP Server
zaycruz
-
security
A
license
-
quality
Facilitates isolated code execution within Docker containers, enabling secure multi-language script execution and integration with language models like Claude via the Model Context Protocol.
Last updated -
2
Python
MIT License
Python MCP Sandbox
JohanLi233
-
security
A
license
-
quality
An interactive Python code execution environment that allows users and LLMs to safely execute Python code and install packages in isolated Docker containers.
Last updated -
18
Python
Apache 2.0
MCP Docker Sandbox Interpreter
svngoku
-
security
F
license
-
quality
A secure Docker-based environment that allows AI assistants to safely execute code without direct access to the host system by running all code within isolated containers.
Last updated -
2
Python

View all related MCP servers

MCP Executor Server