Python Runtime Interpreter MCP Server

🚀 PRIMS – Python Runtime Interpreter MCP Server

PRIMS is a lightweight open - source Model Context Protocol (MCP) server. It allows LLM agents to execute arbitrary Python code in a secure, disposable sandbox, offering a reliable solution for code execution in an isolated environment.

🚀 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

✨ Features

• One tool, one job. It exposes a single MCP tool – run_code – which executes user - supplied Python code and streams back stdout / stderr.
• Isolated & reproducible. Each call creates a new virtual environment, installs any requested pip packages, mounts optional read - only files, and then cleans up the workspace.
• Zero config. It can work over MCP/stdio or be deployed in Docker.

💻 Usage Examples

Basic Usage

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

Advanced Usage

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

📚 Documentation

Available tools

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.