Unleash the Power of Python in LLMs: A Secure Local Executor via MCP

This document details how to set up a secure local Python executor that seamlessly integrates with Large Language Model (LLM) applications using the Model Context Protocol (MCP). By leveraging Hugging Face's LocalPythonExecutor from the smolagents framework, this solution provides a sandboxed Python environment for executing code generated by LLMs, offering a balance between security and ease of use. This is particularly useful for applications like Claude Desktop, where it can function as a Code Interpreter, similar to the plugin available in ChatGPT.

Key Features

• run_python Tool Exposure: Provides a readily accessible tool for executing Python code snippets.
• Enhanced Security: Executes Python code in a restricted environment, mitigating risks associated with direct eval() usage.
• uv-Powered Virtual Environment: Operates within a dedicated Python virtual environment managed by uv, ensuring dependency isolation.
• No File I/O: Prevents unauthorized file system access, further enhancing security.
• Restricted Import List: Limits available modules to a curated list of safe and commonly used libraries:
  • collections
  • datetime
  • itertools
  • math
  • queue
  • random
  • re
  • stat
  • statistics
  • time
  • unicodedata

Security Considerations

Executing code generated by LLMs on your local machine requires careful consideration of security implications. While solutions involving command-line execution or direct eval() should be avoided due to inherent risks, options like VMs or Docker containers offer robust isolation but can be resource-intensive and complex to set up. Third-party Python runtime services provide another alternative, but often require registration and API keys.

This MCP server, built upon Hugging Face's LocalPythonExecutor, strikes a balance between security and convenience. It offers a more secure execution environment compared to direct Python interpretation while remaining easier to set up than containerized or remote solutions.

As highlighted by the Hugging Face team:

To add a first layer of security, code execution in smolagents is not performed by the vanilla Python interpreter. We have re-built a more secure LocalPythonExecutor from the ground up.

For a deeper understanding of the security measures implemented, refer to the official documentation.

Installation and Execution Guide

1. Install uv: Follow the official installation instructions for your operating system (e.g., brew install uv on macOS).
2. Clone the Repository: git clone <repository_url> and cd mcp_safe_local_python_executor.
3. Start the Server: Execute uv run mcp_server.py. This command automatically creates a virtual environment, installs necessary dependencies (smolagents, mcp), and starts the MCP server.

Claude Desktop Integration

1. Ensure Claude Desktop is Installed: Download and install Claude for Desktop from claude.ai.
2. Locate the Configuration File:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Alternatively, open Claude Desktop -> Settings -> Developer -> click "Edit Config".
3. Add the MCP Server Configuration: Insert the following JSON snippet into the configuration file:

{
    "mcpServers": {
        "safe-local-python-executor": {
            "command": "uv",
            "args": [
                "--directory", 
                "/path/to/mcp_local_python_executor/",
                "run",
                "mcp_server.py"
            ]
        }
    }
}

*   **Important:** Replace `/path/to/mcp_local_python_executor/` with the actual path to the cloned repository.

4. Restart Claude Desktop: This ensures the new configuration is loaded. 5. Access the Python Executor: The Python executor tool will now be available within Claude, indicated by a hammer icon in the message input field.

Example Prompts for Claude

• "Calculate the factorial of 5 using Python."
• "Generate a list of prime numbers up to 100 using Python."
• "Solve the equation x^2 + 5x + 6 = 0 using Python."

Development Workflow

1. Clone the Repository: git clone <repository_url>.
2. Create and Activate Virtual Environment: uv venv .venv.
3. Install Development Dependencies: uv sync --group dev.
4. Run Tests: python -m pytest tests/.