MCP Run Python

🚀 MCP Run Python

MCP Run Python is an MCP server that enables the execution of Python code in a sandbox. It uses Pyodide in Deno, isolating the code from the rest of the operating system.

🚀 Quick Start

To use this server, you must have both Python and Deno installed.

✨ Features

• Secure Execution: Run Python code in a sandboxed WebAssembly environment.
• Package Management: Automatically detects and installs required dependencies.
• Complete Results: Captures standard output, standard error, and return values.
• Asynchronous Support: Runs async code properly.
• Error Handling: Provides detailed error reports for debugging.

(This code was previously part of Pydantic AI but was moved to a separate repo to make it easier to maintain.)

📦 Installation

The server can be run with deno installed using uvx:

uvx mcp-run-python [-h] [--version] [--port PORT] [--deps DEPS] {stdio,streamable-http,example}

where:

• stdio runs the server with the Stdio MCP transport — suitable for running the process as a subprocess locally.
• streamable-http runs the server with the Streamable HTTP MCP transport - suitable for running the server as an HTTP server to connect locally or remotely. This supports stateful requests, but does not require the client to hold a stateful connection like SSE.
• example will run a minimal Python script using numpy, useful for checking that the package is working. For the code to run successfully, you'll need to install numpy using uvx mcp-run-python --deps numpy example.

💻 Usage Examples

Basic Usage

Usage with Pydantic AI

from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStdio
from mcp_run_python import deno_args_prepare

import logfire

logfire.configure()
logfire.instrument_mcp()
logfire.instrument_pydantic_ai()

server = MCPServerStdio('uvx', args=['mcp-run-python@latest', 'stdio'], timeout=10)
agent = Agent('claude-3-5-haiku-latest', toolsets=[server])


async def main():
    async with agent:
        result = await agent.run('How many days between 2000-01-01 and 2025-03-18?')
    print(result.output)
    #> There are 9,208 days between January 1, 2000, and March 18, 2025.

if __name__ == '__main__':
    import asyncio
    asyncio.run(main())

Usage in codes as an MCP server

First install the mcp-run-python package:

pip install mcp-run-python
# or
uv add mcp-run-python

With mcp-run-python installed, you can also run deno directly with prepare_deno_env or async_prepare_deno_env

from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStdio
from mcp_run_python import async_prepare_deno_env

import logfire

logfire.configure()
logfire.instrument_mcp()
logfire.instrument_pydantic_ai()


async def main():
    async with async_prepare_deno_env('stdio') as deno_env:
        server = MCPServerStdio('deno', args=deno_env.args, cwd=deno_env.cwd, timeout=10)
        agent = Agent('claude-3-5-haiku-latest', toolsets=[server])
        async with agent:
            result = await agent.run('How many days between 2000-01-01 and 2025-03-18?')
        print(result.output)
        #> There are 9,208 days between January 1, 2000, and March 18, 2025.

if __name__ == '__main__':
    import asyncio
    asyncio.run(main())

Note: prepare_deno_env can take deps as a keyword argument to install dependencies. As well as returning the args needed to run mcp_run_python, prepare_deno_env creates a new deno environment and installs the dependencies so they can be used by the server.

Usage in code with code_sandbox

from mcp_run_python import code_sandbox

code = """
import numpy
a = numpy.array([1, 2, 3])
print(a)
a
"""

async def main():
    async with code_sandbox(dependencies=['numpy']) as sandbox:
        result = await sandbox.eval(code)
        print(result)


if __name__ == '__main__':
    import asyncio

    asyncio.run(main())

Under the hood, code_sandbox runs an MCP server using stdio. You can run multiple code blocks with a single sandbox.

📚 Documentation

Logging

MCP Run Python supports emitting stdout and stderr from the python execution as MCP logging messages.

For logs to be emitted you must set the logging level when connecting to the server. By default, the log level is set to the highest level, emergency.

Dependencies

mcp_run_python uses a two step process to install dependencies while avoiding any risk that sandboxed code can edit the filesystem.

• deno is first run with write permissions to the node_modules directory and dependencies are installed, causing wheels to be written to ``.
• deno is then run with read-only permissions to the node_modules directory to run untrusted code.

Dependencies must be provided when initializing the server so they can be installed in the first step.