Safe Local Python Executor

1# Safe Local Python Executor
2 
3An MCP server (stdio transport) that wraps Hugging Face's [`LocalPythonExecutor`](https://github.com/huggingface/smolagents/blob/main/src/smolagents/local_python_executor.py)
4(from the [`smolagents`](https://huggingface.co/docs/smolagents/en/index) framework). It is a custom Python runtime that 
5provides basic isolation/security when running Python code generated by LLMs locally. It does not require Docker or VM.
6This 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.
7In 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).
8 
9<img width="1032" alt="image" src="https://github.com/user-attachments/assets/3b820bfc-970a-4315-8f2d-970591c6fdae" />
10 
11## Features
12 
13- Exposes `run_python` tool
14- Safer execution of Python code compared to direct use of Python `eva()l`
15- Ran via uv in Python venv
16- No file I/O ops are allowed
17- Restricted list of imports
18    - collections
19    - datetime
20    - itertools
21    - math
22    - queue
23    - random
24    - re
25    - stat
26    - statistics
27    - time
28    - unicodedata
29 
30## Security
31 
32Be 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.
33 
34`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:
35 
36>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.
37 
38Read more [here](https://huggingface.co/docs/smolagents/en/tutorials/secure_code_execution#local-code-execution).
39 
40## Installation and Execution
41 
42### Installing via Smithery
43 
44To install Safe Local Python Executor for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@maxim-saplin/mcp_safe_local_python_executor):
45 
46```bash
47npx -y @smithery/cli install @maxim-saplin/mcp_safe_local_python_executor --client claude
48```
49 
50### Installing Manually
511. Install `uv` (e.h. `brew install uv` on macOS or use [official docs](https://docs.astral.sh/uv/getting-started/installation/#__tabbed_1_2))
522. Clone the repo, change the directory `cd mcp_safe_local_python_executor`
533. The server can be started via command line `uv run mcp_server.py`, venv will be created automatically, depedencies (smollagents, mcp) will be installed
54 
55 
56## Configuring Claude Desktop
57 
581. Make sure you have Claude for Desktop installed (download from [claude.ai](https://claude.ai/desktop))
592. Edit your Claude for Desktop configuration file:
60   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
61   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
62   - Or open Claude Desktop -> Settings -> Developer -> click "Edit Config" button
63 
643. Add the following configuration:
65 
66```json
67{
68    "mcpServers": {
69        "safe-local-python-executor": {
70            "command": "uv",
71            "args": [
72                "--directory", 
73                "/path/to/mcp_local_python_executor/",
74                "run",
75                "mcp_server.py"
76            ]
77        }
78    }
79}
80```
81 
824. Restart Claude for Desktop
835. The Python executor tool will now be available in Claude (you'll see hammer icon in the message input field)
84 
85## Example Prompts
86 
87Once configured, you can use prompts like:
88 
89- "Calculate the factorial of 5 using Python"
90- "Create a list of prime numbers up to 100"
91- "Solve this equation (use Python): x^2 + 5x + 6 = 0"
92 
93 
94## Development
95 
96Clone the repo. Use `uv` to create venv, install dev dependencies, run tests:
97 
98```
99uv venv .venv
100uv sync --group dev
101python -m pytest tests/
102```
103 
104-----------------------
105 
106<a href="https://glama.ai/mcp/servers/@maxim-saplin/mcp_safe_local_python_executor">
107  <img width="380" height="200" src="https://glama.ai/mcp/servers/@maxim-saplin/mcp_safe_local_python_executor/badge" />
108</a>
109 
110[![smithery badge](https://smithery.ai/badge/@maxim-saplin/mcp_safe_local_python_executor)](https://smithery.ai/server/@maxim-saplin/mcp_safe_local_python_executor)
111 
112[![MseeP.ai Security Assessment Badge](https://mseep.net/pr/maxim-saplin-mcp-safe-local-python-executor-badge.png)](https://mseep.ai/app/maxim-saplin-mcp-safe-local-python-executor)
113 
114