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

2. Launch the server

3. Docker

Examples

List available tools

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

Expected output (tool names and descriptions may vary):

Run code via the MCP server

Mount a dataset once & reuse it

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

Inspect your session workspace

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

Download an artifact

Small artifacts can be fetched directly:

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.