# 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:

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

### Step 2 — Run setup

```bash
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:

```bash
claude mcp list
```

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

```bash
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)`):

```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`:

```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:

```json
"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:

```bash
# 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:

```bash
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:

```python
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.