# Python Runtime Interpreter MCP Server

> PRIMS is a lightweight, open-source Model Context Protocol (MCP) server that lets LLM agents safely execute arbitrary Python code in a secure, throw-away sandbox.

- **Type:** MCP server
- **Install:** `agentstack add mcp-hileamlakb-python-runtime-interpreter-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [hileamlakB](https://agentstack.voostack.com/s/hileamlakb)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [hileamlakB](https://github.com/hileamlakB)
- **Source:** https://github.com/hileamlakB/Python-Runtime-Interpreter-MCP-Server

## Install

```sh
agentstack add mcp-hileamlakb-python-runtime-interpreter-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# PRIMS – Python Runtime Interpreter MCP Server

PRIMS is a tiny open-source **Model Context Protocol (MCP)** server that lets LLM agents run arbitrary Python code in a secure, throw-away sandbox.

•   **One tool, one job.**  Exposes a single MCP tool – `run_code` – that executes user-supplied Python and streams back `stdout / stderr`.

•   **Isolated & reproducible.**  Each call spins up a fresh virtual-env, installs any requested pip packages, mounts optional read-only files, then nukes the workspace.

•   **Zero config.**  Works over MCP/stdio or drop it in Docker.

---

## Quick-start

### 1. Local development environment

```bash
chmod +x scripts/setup_env.sh   # once, to make the script executable
./scripts/setup_env.sh          # creates .venv & installs deps

# activate the venv in each new shell
source .venv/bin/activate
```

### 2. Launch the server

```bash
python -m server.main         # binds http://0.0.0.0:9000/mcp
```

### 3. Docker

```bash
# Quick one-liner (build + run)
chmod +x scripts/docker_run.sh
./scripts/docker_run.sh         # prints the MCP URL when ready
```

## Examples

### List available tools

You can use the provided script to list all tools exposed by the server:

```bash
python examples/list_tools.py
```

Expected output (tool names and descriptions may vary):

```
Available tools:
- run_code: Execute Python code in a secure sandbox with optional dependencies & file mounts.
- list_dir: List files/directories in your session workspace.
- preview_file: Preview up to 8 KB of a text file from your session workspace.
- persist_artifact: Upload an output/ file to a presigned URL for permanent storage.
- mount_file: Download a remote file once per session to `mounts/`.
```

### Run code via the MCP server

```bash
python examples/run_code.py
```

### Mount a dataset once & reuse it

```bash
python examples/mount_and_run.py
```

This mounts a CSV with `mount_file` and then reads it inside `run_code` without re-supplying the URL.

### Inspect your session workspace

```bash
python examples/inspect_workspace.py
```

This shows how to use the **`list_dir`** and **`preview_file`** tools to browse files your code created.

### Persist an artifact to permanent storage

The **`persist_artifact`** tool uploads a file from your `output/` directory to a presigned URL.

Example (Python):

```python
await client.call_tool("persist_artifact", {
    "relative_path": "plots/plot.png",
    "presigned_url": "https://bucket.s3.amazonaws.com/...signature...",
})
```

### Download an artifact

Small artifacts can be fetched directly:

```bash
curl -H "mcp-session-id: " \
     http://localhost:9000/artifacts/plots/plot.png -o plot.png
```

---

## Available tools

| Tool                | Purpose |
|---------------------|---------------------------------------------------------------|
| `run_code`          | Execute Python in an isolated sandbox with optional pip deps. |
| `list_dir`          | List files/directories inside your session workspace.        |
| `preview_file`      | Return up to 8 KB of a text file for quick inspection.        |
| `persist_artifact`  | Upload an `output/` file to a client-provided presigned URL. |
| `mount_file`        | Download a remote file once per session to `mounts/`. |

See the `examples/` directory for end-to-end demos.

## Contributing
Contributions are welcome! Feel free to open issues, suggest features, or submit pull requests to help improve PRIMS.

If you find this project useful, please consider leaving a ⭐ to show your support.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [hileamlakB](https://github.com/hileamlakB)
- **Source:** [hileamlakB/Python-Runtime-Interpreter-MCP-Server](https://github.com/hileamlakB/Python-Runtime-Interpreter-MCP-Server)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-hileamlakb-python-runtime-interpreter-mcp-server
- Seller: https://agentstack.voostack.com/s/hileamlakb
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.