MCP Safe Local Python Executor

🚀 Secure Local Python Executor

A server that encapsulates the LocalPythonExecutor (from the smolagents framework) from Hugging Face using the MCP protocol (stdio transmission). It is a custom Python runtime that provides basic isolation and security when you run code generated by an LLM locally. It does not require Docker or a virtual machine. This package allows exposing the Python executor as a tool to LLM applications via MCP (Model Context Protocol), such as Claude Desktop, Cursor, or any other MCP-compatible client. For Claude Desktop, this tool is a simple way to add a missing code interpreter (which has been available in ChatGPT for some time).

🚀 Quick Start

The Secure Local Python Executor is a great solution for safely running LLM-generated code locally. It offers a balance between ease of setup and security.

✨ Features

• Provides the run_python tool.
• Executes code more securely than directly using Python's eval().
• Runs in a Python virtual environment via uv.
• Does not allow any file I/O operations.
• Has a restricted import list:
  • collections
  • datetime
  • itertools
  • math
  • queue
  • random
  • re
  • stat
  • statistics
  • time
  • unicodedata

🔒 Security

Be cautious when running code generated by an LLM on your machine. Avoid MCP servers that run Python via the command line or use eval(). The safest option is to use a VM or Docker container, although this requires more setup effort. There are third-party services that provide Python runtimes, but they require registration and API keys.

The LocalPythonExecutor provides a good balance between using a local Python environment directly (easier to set up) and remote execution in a Docker container, virtual machine, or third-party service (more secure). The Hugging Face team spent a lot of time building a more secure local Python executor from scratch for its code agents:

To add a first layer of security, the execution of code in smolagents is not done using the raw Python interpreter. We rebuilt a more secure LocalPythonExecutor from scratch.

Learn more here.

📦 Installation

1. Install uv (e.g., on macOS, use brew install uv or refer to the official documentation).
2. Clone the repository and navigate to the directory: cd mcp_safe_local_python_executor.
3. Run the server via the command line: uv run mcp_server.py. This will automatically create a virtual environment and install the dependencies (smollagents, mcp).

🛠️ Configuration for Claude Desktop

To use this MCP server, configure Claude Desktop as follows:

1. Open the settings in Claude Desktop.
2. Enable "Custom MCP Server" in the "Experiments" section.
3. Set MCP_SERVER_ADDRESS to http://localhost:5000.
4. Start Claude Desktop.

💻 Usage Examples

Basic Usage

# Install the necessary dependencies
pip install uvicorn fastapi

# Create a new file named mcp_server.py and add the following content:
from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles

app = FastAPI()
static_files = StaticFiles(directory=".")
app.mount("/static", static_files)

@app.get("/")
async def root():
    return {"message": "MCP server has started"}

Run this script:

uvicorn mcp_server:app --reload

Then, access http://localhost:5000 to test your MCP server.

```markdown
## 📄 Icon
<a href="https://github.com/huggingface/smolagents/blob/main/src/smolagents/local_python_executor.py" target="_blank"></a>