https://github.com/maxim-saplin/mcp_safe_local_python_executor
Stdio MCP Server wrapping custom Python runtime (LocalPythonExecutor) from Hugging Faces' `smolagents` framework. The runtime combines the ease of setup (compared to docker, VM, cloud runtimes) while providing safeguards and limiting operations/imports that are allowed inside the runtime.
https://github.com/maxim-saplin/mcp_safe_local_python_executor
Last synced: 2 months ago
JSON representation
Stdio MCP Server wrapping custom Python runtime (LocalPythonExecutor) from Hugging Faces' `smolagents` framework. The runtime combines the ease of setup (compared to docker, VM, cloud runtimes) while providing safeguards and limiting operations/imports that are allowed inside the runtime.
- Host: GitHub
- URL: https://github.com/maxim-saplin/mcp_safe_local_python_executor
- Owner: maxim-saplin
- License: mit
- Created: 2025-03-27T12:36:20.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2025-05-01T15:59:57.000Z (2 months ago)
- Last Synced: 2025-05-01T16:44:36.231Z (2 months ago)
- Language: Python
- Homepage:
- Size: 132 KB
- Stars: 15
- Watchers: 1
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-devops-mcp-servers - maxim-saplin/mcp_safe_local_python_executor - Safe Python interpreter based on HF Smolagents `LocalPythonExecutor` (Cloud Infrastructure / 🖥️ Command Line)
- awesome-devops-mcp-servers - maxim-saplin/mcp_safe_local_python_executor - Safe Python interpreter based on HF Smolagents `LocalPythonExecutor` (Cloud Infrastructure / 🖥️ Command Line)
- awesome-mcp-zh - maxim-saplin/mcp_safe_local_python_executor
- awesome-mcp-servers - SafePythonExecutor - Stdio MCP Server wrapping custom Python runtime (LocalPythonExecutor) from Hugging Faces' `smolagents` framework. The runtime combines the ease of setup (compared to docker, VM, cloud runtimes) while providing safeguards and limiting operations/imports that are allowed inside the runtime. (Table of Contents / Security)
- awesome-mcp-servers - SafePythonExecutor - Stdio MCP Server wrapping custom Python runtime (LocalPythonExecutor) from Hugging Faces' `smolagents` framework. The runtime combines the ease of setup (compared to docker, VM, cloud runtimes) while providing safeguards and limiting operations/imports that are allowed inside the runtime. (Table of Contents / Security)
- awesome-mcp-registry - ❌ safe-local-python-executor
- awesome-mcp-registry - ❌ safe-local-python-executor
- mcp-index - Safe Local Python Executor - A safe execution environment for running Python code generated by language models locally without requiring Docker or virtual machines. It provides basic isolation and security features, making it suitable for integrating Python capabilities into various applications. (Developer Tools)
README
# Safe Local Python Executor
An MCP server (stdio transport) that wraps Hugging Face's [`LocalPythonExecutor`](https://github.com/huggingface/smolagents/blob/main/src/smolagents/local_python_executor.py)
(from the [`smolagents`](https://huggingface.co/docs/smolagents/en/index) framework). It is a custom Python runtime that
provides basic isolation/security when running Python code generated by LLMs locally. It does not require Docker or VM.
This package allows to expose the Python executor via MCP (Model Context Protocol) as a tool for LLM apps like Claude Desktop, Cursor or any other MCP compatible client.
In case of Claude Desktop this tool is an easy way to add a missing Code Interpreter (available as a plugin in ChatGPT for quite a while already).
## Features
- Exposes `run_python` tool
- Safer execution of Python code compared to direct use of Python `eva()l`
- Ran via uv in Python venv
- No file I/O ops are allowed
- Restricted list of imports
- collections
- datetime
- itertools
- math
- queue
- random
- re
- stat
- statistics
- time
- unicodedata
## Security
Be careful with execution of code produced by LLM on your machine, stay away from MCP servers that run Python via command line or using `eval()`. The safest option is using a VM or a docker container, though it requires some effort to set-up, consumes resources/slower. There're 3rd party servcices providing Python runtime, though they require registration, API keys etc.
`LocalPythonExecutor` provides a good balance between direct use of local Python environment (which is easier to set-up) AND remote execution in Dokcer container or a VM/3rd party service (which is safe). Hugginng Face team has invested time into creating a quick and safe option to run LLM generated code used by their code agents. This MCP server builds upon it:
>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.
Read more [here](https://huggingface.co/docs/smolagents/en/tutorials/secure_code_execution#local-code-execution).
## Installation and Execution
1. Install `uv` (e.h. `brew install uv` on macOS or use [official docs](https://docs.astral.sh/uv/getting-started/installation/#__tabbed_1_2))
2. Clone the repo, change the directory `cd mcp_safe_local_python_executor`
3. The server can be started via command line `uv run mcp_server.py`, venv will be created automatically, depedencies (smollagents, mcp) will be installed
## Configuring Claude Desktop
1. Make sure you have Claude for Desktop installed (download from [claude.ai](https://claude.ai/desktop))
2. Edit your Claude for Desktop configuration file:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Or open Claude Desktop -> Settings -> Developer -> click "Edit Config" button
3. Add the following configuration:
```json
{
"mcpServers": {
"safe-local-python-executor": {
"command": "uv",
"args": [
"--directory",
"/path/to/mcp_local_python_executor/",
"run",
"mcp_server.py"
]
}
}
}
```
4. Restart Claude for Desktop
5. The Python executor tool will now be available in Claude (you'll see hammer icon in the message input field)
## Example Prompts
Once configured, you can use prompts like:
- "Calculate the factorial of 5 using Python"
- "Create a list of prime numbers up to 100"
- "Solve this equation (use Python): x^2 + 5x + 6 = 0"
## Development
Clone the repo. Use `uv` to create venv, install dev dependencies, run tests:
```
uv venv .venv
uv sync --group dev
python -m pytest tests/
```
-----------------------
