python-executor-mcp

A local MCP (Model Context Protocol) server that lets your coding agents execute Python code and script files directly on your machine — with built-in package installation support.

---

Overview

This server exposes three tools to any MCP-compatible agent:

Tool	Description
run_python_code	Execute a string of Python code and return stdout/stderr
run_python_file	Execute a .py file by absolute path, with optional CLI args
install_python_package	Install a pip package into the server's virtual environment

All three tools return a dict with stdout, stderr, and returncode.

---

How It Works

Each MCP client (Claude Code, VS Code, Cursor, Antigravity) spawns a fresh instance of server.py on demand via stdio. They don't share a running process — but they all point at the same script on disk. This means:

• You only maintain one codebase
• Updates to server.py are picked up automatically on the next agent spawn
• No daemon to manage, no ports to open

---

Prerequisites

• Python 3.10 or later
• pip available on your system
• (Optional) Claude Code CLI installed, for auto-registration

---

Installation

Step 1 — Clone the repo

After downloading this folder, initialize it as a git repo and push it wherever you like:

cd python-executor-mcp
git init
git add .
git commit -m "Initial commit"

Step 2 — Run setup

chmod +x setup.sh
./setup.sh

This script will:

1. Create a .venv virtual environment inside the project folder
2. Install mcp and fastmcp into it
3. Print the absolute paths you'll need for manual tool registration
4. Automatically register the server with Claude Code at user scope (if claude is in your PATH)

Important: After running setup, note the two paths printed — you'll use them in the steps below.

---

Registering With Each Tool

Replace /ABSOLUTE/PATH/TO/python-executor-mcp with your actual path everywhere below.
Run pwd inside the project folder to get it.

---

Claude Code (Terminal)

If setup.sh detected Claude Code, this was done automatically. To verify:

claude mcp list

To register manually (user scope = available in all projects):

claude mcp add python-executor --scope user -- \
  /ABSOLUTE/PATH/TO/python-executor-mcp/.venv/bin/python \
  /ABSOLUTE/PATH/TO/python-executor-mcp/server.py

---

VS Code

Add the following to your user settings.json
(open it via Cmd+Shift+P → Preferences: Open User Settings (JSON)):

"mcp": {
  "servers": {
    "python-executor": {
      "type": "stdio",
      "command": "/ABSOLUTE/PATH/TO/python-executor-mcp/.venv/bin/python",
      "args": ["/ABSOLUTE/PATH/TO/python-executor-mcp/server.py"]
    }
  }
}

A ready-to-edit example is in config-examples/vscode-settings.json.

---

Cursor

Edit (or create) ~/.cursor/mcp.json:

{
  "mcpServers": {
    "python-executor": {
      "command": "/ABSOLUTE/PATH/TO/python-executor-mcp/.venv/bin/python",
      "args": ["/ABSOLUTE/PATH/TO/python-executor-mcp/server.py"]
    }
  }
}

A ready-to-edit example is in config-examples/cursor-mcp.json.

---

Antigravity (and other MCP clients)

Most MCP-compatible tools use the same JSON shape. Look for a config file named mcp.json, mcp_servers.json, or a mcpServers key in the tool's main config, and add:

"python-executor": {
  "command": "/ABSOLUTE/PATH/TO/python-executor-mcp/.venv/bin/python",
  "args": ["/ABSOLUTE/PATH/TO/python-executor-mcp/server.py"]
}

A generic template is in config-examples/generic-mcp.json.

---

Updating the Server

Since all clients point to the same server.py, any change you make is picked up automatically:

# Edit server.py, then commit
git add server.py
git commit -m "Add new tool"

No re-registration needed.

---

Adding New Python Dependencies

Agents can install packages themselves at runtime using the install_python_package tool. To pre-install something permanently:

source .venv/bin/activate
pip install some-package
pip freeze > requirements.txt
deactivate

Then commit the updated requirements.txt.

---

Security Note

run_python_code and run_python_file execute arbitrary code with your user's full permissions — file system access, network calls, everything. This is intentional for a local dev tool.

If you want to sandbox execution (e.g. for untrusted agents), replace the subprocess.run call in _run() with a Docker invocation:

result = subprocess.run(
    ["docker", "run", "--rm", "--network", "none",
     "-v", f"{tmp_path}:/script.py:ro",
     "python:3.12-slim", "python", "/script.py"],
    capture_output=True, text=True, timeout=timeout
)

---

Project Structure

python-executor-mcp/
├── server.py               # The MCP server — all three tools live here
├── requirements.txt        # Python dependencies for the server itself
├── setup.sh                # One-time setup: creates .venv, installs deps, registers Claude Code
├── .gitignore              # Excludes .venv and cache files
├── README.md               # This file
└── config-examples/
    ├── cursor-mcp.json     # Paste into ~/.cursor/mcp.json
    ├── vscode-settings.json  # Paste into VS Code user settings.json
    └── generic-mcp.json    # Template for any other MCP-compatible tool

---

License

MIT — do whatever you want with it.