pierre-cheneau/uv-exec-mcp

MCP UV HTTP Executor

A secure, 2-server MCP architecture for executing Python scripts using uv through HTTP communication, designed to eliminate subprocess conflicts and provide clean separation of concerns.

🏗️ Architecture Overview

Claude Desktop
    ↓ STDIO/MCP Protocol
MCP HTTP Client (mcp_http_client.py)
    ↓ HTTP Requests
Execution Server (execution_server.py)
    ↓ subprocess
UV Runtime → Python Scripts
    ↓ 
Working Directory Sandbox

Why 2 Servers?

• 🚫 No Subprocess Conflicts: HTTP communication eliminates stdio conflicts between MCP and script execution
• 🎯 Clean Separation: MCP protocol handling separated from script execution
• 🐛 Easy Debugging: Test each component independently, clear error boundaries
• 📈 Scalable: Execution server can be moved to different hosts, shared between clients
• 🔒 Secure: Working directory sandbox controlled by execution server

🚀 Quick Start

1. Installation

# Clone the repository
git clone <repository-url>
cd mcp-uv-http-executor

# Install UV if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

2. Setup Your Working Directory

# Create a directory for your Python scripts
mkdir my_python_scripts
cd my_python_scripts

# Create a test script
echo 'print("Hello from UV HTTP MCP!")' > hello.py
echo 'print("Current time:", __import__("datetime").datetime.now())' > time_test.py

3. Start the Servers

Terminal 1: Start Execution Server (controls working directory)

# IMPORTANT: Start from your scripts directory!
cd my_python_scripts
uv run ../execution_server.py

# You should see:
# [START] Script Execution Server
# [DIR] Working directory: /path/to/my_python_scripts
# [READY] Ready to execute Python scripts!

Terminal 2: Start MCP Client (directory doesn't matter)

# Can be started from anywhere
uv run mcp_http_client.py

4. Configure Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "uv_http_executor": {
      "command": "uv",
      "args": ["run", "/full/path/to/mcp_http_client.py"]
    }
  }
}

5. Test It!

Open Claude Desktop and try:

• "Execute the hello.py script"
• "Run time_test.py and show me the output"
• "Check if the execution server is running"

🛠️ Available Tools

Execute Python Script

execute_python_script(script_path: str, timeout: int = 30)

Execute any Python script in your working directory with configurable timeout (max 120s).

Check Server Status

check_execution_server()

Verify that the execution server is running and healthy.

Test Scripts

test_hello_world_http(timeout: int = 30)
test_minimal_http(timeout: int = 10)

Built-in test scripts for verifying the setup.

Architecture Info

get_http_server_info()

Get detailed information about the 2-server architecture.

📁 Working Directory Configuration

⚠️ IMPORTANT: Working directory is controlled by where you start execution_server.py!

# ✅ CORRECT: Start execution server in scripts directory
cd /path/to/your/scripts
uv run /path/to/execution_server.py

# ❌ WRONG: Start execution server elsewhere and expect it to find scripts
cd /some/other/path
uv run execution_server.py  # Scripts won't be found!

The execution server uses Path.cwd() as the working directory, so:

• All script paths are relative to where you started the execution server
• Path traversal is prevented (no ../ allowed)
• Only .py files can be executed
• MCP client location doesn't affect script execution

🔧 Configuration

Environment Variables

Execution Server:

export EXECUTION_PORT=8080          # HTTP server port (default: 8080)
export EXECUTION_HOST=127.0.0.1     # HTTP server host (default: 127.0.0.1)
export MAX_SCRIPT_TIMEOUT=120       # Maximum script timeout (default: 120)

MCP Client:

export EXECUTION_SERVER_URL=http://127.0.0.1:8080  # Execution server URL
export MCP_HTTP_TIMEOUT=10                          # HTTP timeout buffer (default: 10)

Script Types Supported

The execution server automatically handles different script types:

• Standalone scripts: Basic Python scripts using standard library
• PEP 723 scripts: Scripts with inline dependencies:

  #!/usr/bin/env -S uv run
  # /// script
  # dependencies = ["requests", "pandas"]
  # ///
  import requests
  

• Project scripts: Scripts in directories with pyproject.toml or uv.lock

🐛 Troubleshooting

Common Issues

"Cannot connect to execution server"

# Check if execution server is running
curl http://127.0.0.1:8080/health

# If not running, start it:
cd your_scripts_directory
uv run execution_server.py

"Invalid script path" or "Script not found"

# Check working directory of execution server
# Look for this line in execution server output:
# [DIR] Working directory: /current/working/directory

# Make sure your script is in that directory:
ls -la /current/working/directory/your_script.py

Port 8080 already in use

# Find what's using the port
lsof -i :8080

# Kill the process or change port
export EXECUTION_PORT=8081
uv run execution_server.py

Debug Mode

Start the execution server with verbose output:

# The execution server already provides detailed logging
uv run execution_server.py
# Watch for [EXEC] messages showing command execution

Test HTTP communication directly:

# Test execution server directly
curl -X POST http://127.0.0.1:8080/execute \
  -H "Content-Type: application/json" \
  -d '{"script_path": "hello.py", "timeout": 10}'

📋 Project Structure

mcp-uv-http-executor/
├── README.md                    # This file
├── SPECS.md                     # High-level specifications
├── execution_server.py          # HTTP execution server (FastAPI)
├── mcp_http_client.py           # MCP client server (FastMCP)
└── specs/                       # Detailed specifications
    ├── core-system.md           # Architecture details
    ├── mcp-interface.md         # MCP tools and interface
    └── configuration.md         # Deployment and configuration

🔒 Security Features

• Sandboxed Execution: Scripts can only access files in the working directory
• Path Validation: Prevents directory traversal attacks (../ blocked)
• File Type Restriction: Only .py files can be executed
• Timeout Protection: Scripts are terminated after configurable timeout
• Process Isolation: Each script runs in its own subprocess
• Safe Environment: Limited environment variables passed to scripts

🚀 Production Deployment

Systemd Service

Create /etc/systemd/system/mcp-execution-server.service:

[Unit]
Description=MCP Python UV Execution Server
After=network.target

[Service]
Type=simple
User=mcp-executor
Group=mcp-executor
WorkingDirectory=/opt/scripts  # Your scripts directory
ExecStart=/usr/local/bin/uv run /opt/mcp-uv-executor/execution_server.py
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Start the service:

sudo systemctl enable mcp-execution-server
sudo systemctl start mcp-execution-server

Docker Deployment

FROM python:3.11-slim
RUN pip install uv
WORKDIR /app/scripts
COPY execution_server.py /app/
VOLUME ["/app/scripts"]
EXPOSE 8080
CMD ["uv", "run", "/app/execution_server.py"]

🧪 Development & Testing

Running Tests

# Create test environment
mkdir test_scripts
cd test_scripts

# Create test files
echo 'print("Hello World!")' > hello.py
echo 'import sys; print("Args:", sys.argv[1:])' > args_test.py
echo 'import time; time.sleep(2); print("Done")' > slow_test.py

# Start execution server
uv run ../execution_server.py &

# Test with MCP inspector
mcp dev ../mcp_http_client.py

Integration Testing

# Test HTTP API directly
curl -X POST http://127.0.0.1:8080/execute \
  -H "Content-Type: application/json" \
  -d '{"script_path": "hello.py", "timeout": 10}'

# Test MCP tools
echo '{"method": "tools/call", "params": {"name": "check_execution_server"}}' | \
  uv run mcp_http_client.py

📚 Documentation

• : High-level project specifications
• : Detailed architecture documentation
• : MCP tools and API reference
• : Deployment and configuration guide

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test with both servers running
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🙋‍♂️ Support

For issues and questions:

1. Check the troubleshooting section
2. Review the
3. Open an issue with:
   • Execution server logs
   • MCP client output
   • Steps to reproduce

Key Takeaway: This 2-server architecture eliminates the stdio conflicts that plague single-server MCP implementations while providing a clean, debuggable, and scalable solution for Python script execution! 🎉