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
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
python -m server.main # binds http://0.0.0.0:9000/mcp
3. Docker
# 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:
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/<path>`.
Run code via the MCP server
python examples/run_code.py
Mount a dataset once & reuse it
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
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):
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:
curl -H "mcp-session-id: <your-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/<path>. |
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.
Metadata
Release files for iflow-mcp_hileamlakb-prims 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_hileamlakb_prims-0.1.0.tar.gz | 13.7 kB | Without provenance | Details for iflow_mcp_hileamlakb_prims-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_hileamlakb_prims-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_hileamlakb_prims-0.1.0-py3-none-any.whl |
Total release size: 31.5 kB
Release files / iflow_mcp_hileamlakb_prims-0.1.0.tar.gz
| Download URL | iflow_mcp_hileamlakb_prims-0.1.0.tar.gz |
|---|---|
| Size | 13.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
99f4ed955481ea653bd03efb796e42fa1059ca84c4e153af29954f85a190b98f
|
|
BLAKE2b-256 checksum How to use checksums |
d5c938c53d815b3026ccb45376744fbdd5ae7cbbb2b24de0696179dd6c5cff16
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.0 {"installer":{"name":"uv","version":"0.10.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / iflow_mcp_hileamlakb_prims-0.1.0-py3-none-any.whl
| Download URL | iflow_mcp_hileamlakb_prims-0.1.0-py3-none-any.whl |
|---|---|
| Size | 17.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1639ad2526baf9960f96dc278328a62e5f6aeef948388fbbd5aad6ceafd0df88
|
|
BLAKE2b-256 checksum How to use checksums |
79c86bc1a7f76956c9c936c0ec59f2d9fa6690e9f8951ac13251a05e08657921
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.0 {"installer":{"name":"uv","version":"0.10.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for iflow-mcp_hileamlakb-prims 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.