MCP Safe Local Python Executor

What maxim-saplin/mcp_safe_local_python_executor does

The maxim-saplin/mcp_safe_local_python_executor MCP server makes a restricted Python runtime available to MCP-compatible applications. It wraps Hugging Face Smolagents' LocalPythonExecutor rather than invoking the regular Python interpreter directly. The exposed run_python tool is intended for code generated by an LLM and supports tasks such as calculations, generating number sequences, and solving equations.

The project is designed for local use. It does not depend on Docker or a virtual machine, and it can add a Python execution tool to clients such as Claude Desktop and Cursor. The maxim-saplin/mcp_safe_local_python_executor MCP server is therefore relevant when an agent needs an embedded code interpreter for straightforward computation without sending code to a third-party runtime.

How it works

The server communicates over MCP's stdio transport. When started, it uses LocalPythonExecutor from the Smolagents framework to process Python supplied through the MCP tool. This executor is intended to provide more control than directly evaluating arbitrary Python code.

Execution disallows file I/O operations. Imports are limited to the following modules: collections, datetime, itertools, math, queue, random, re, stat, statistics, time, and unicodedata. This restriction makes the runtime more constrained than a normal local Python environment, so scripts that depend on other packages, filesystem access, or broader operating-system functionality are not suitable.

The restrictions should not be treated as equivalent to a VM or container boundary. The project documentation describes the local executor as a security and convenience compromise, and recommends stronger isolation approaches when the risk of running generated code warrants them.

Setup and configuration

Install uv, clone the repository, and change into the project directory. Running uv run mcp_server.py creates the virtual environment as needed and installs the listed dependencies, including Smolagents and MCP. The same command starts the stdio server.

For Claude Desktop, add an MCP server entry whose command is uv, with arguments that select the cloned project directory and run mcp_server.py. The directory value must point to the local checkout; the example path in the project documentation is a placeholder. Restart Claude Desktop after saving the configuration. The Python executor should then appear as an available tool.

The maxim-saplin/mcp_safe_local_python_executor MCP server does not document API keys, OAuth credentials, or required environment variables. It is operated from the local Python environment created by uv.

Tools and capabilities

• Exposes one documented MCP tool, run_python.
• Executes Python through Smolagents' restricted local executor.
• Supports basic calculations and other code that stays within the permitted runtime.
• Blocks file I/O operations.
• Allows imports only from the documented module list.
• Works with Claude Desktop, Cursor, and other MCP-compatible clients.

Limitations and notes

This is not a general-purpose Python environment. The import allowlist and disabled file operations prevent many scripts from running, and the documentation does not claim complete security isolation. Generated code still runs on the user's machine, so users should assess the risks of allowing an agent to execute code locally. A Docker container or VM may be a better choice when stronger separation is required, although those approaches add setup and resource costs.

The maxim-saplin/mcp_safe_local_python_executor MCP server is provided as a local stdio process rather than a hosted execution service. Its documented installation flow requires the repository and uv; no hosted endpoint or external execution account is described.