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

Related MCP server: Python MCP Sandbox

📋 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

2. Install Dependencies

3. Start the Server

Development Mode (Recommended):

Production Mode:

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:

Response:

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:

3. Health Check

GET /health

Check if the server is running properly.

Response:

🧪 Testing

Using Postman

1. Test Health Check:

   • Method: GET

   • URL: http://localhost:3000/health

2. Test Code Execution:

   • Method: POST

   • URL: http://localhost:3000/execute

   • Headers: Content-Type: application/json

   • Body:

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

3. Test SSE Streaming:

   • Method: GET

   • URL: http://localhost:3000/sse

   • Keep connection open while testing /execute

Using curl

🔧 n8n Integration

Basic Setup

1. Add HTTP Request Node

2. 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:

Data Processing:

File Operations:

📁 Project Structure

🔍 Troubleshooting

Common Issues

1. Docker not running:

   • Ensure Docker Desktop is running

   • Check that it's in Linux containers mode

2. Container not found:

   • Verify my-llm-sandbox image exists: docker images

   • Rebuild if needed: docker build -t my-llm-sandbox .

3. Permission denied:

   • Ensure Docker has proper permissions

   • Check Docker socket access

4. 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

1. Build the image:

   docker build -t mcp-executor .

2. 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

Mathematical Operations

Data Processing

File Operations

🤝 Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Test thoroughly

5. Submit a pull request

📄 License

This project is licensed under the ISC License.

🆘 Support

For issues and questions:

1. Check the troubleshooting section

2. Review the console logs

3. Test with simple code examples

4. Verify Docker setup

Happy coding! 🎉