Skip to content
Back to search

mcp-run-python

MCP server to run Python code in a sandbox.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/pydantic--mcp-run-python/badge.svg)](/listings/pydantic--mcp-run-python)

HTML

<a href="/listings/pydantic--mcp-run-python"><img src="/api/listings/pydantic--mcp-run-python/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 189 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. <h1>MCP Run Python</h1>
  3. </div>
  4. <div align="center">
  5. <a href="https://github.com/pydantic/mcp-run-python/actions/workflows/ci.yml?query=branch%3Amain"><img src="https://github.com/pydantic/mcp-run-python/actions/workflows/ci.yml/badge.svg?event=push" alt="CI"></a>
  6. <a href="https://pypi.python.org/pypi/mcp-run-python"><img src="https://img.shields.io/pypi/v/mcp-run-python.svg" alt="PyPI"></a>
  7. <a href="https://github.com/pydantic/mcp-run-python"><img src="https://img.shields.io/pypi/pyversions/mcp-run-python.svg" alt="versions"></a>
  8. <a href="https://github.com/pydantic/mcp-run-python/blob/main/LICENSE"><img src="https://img.shields.io/github/license/pydantic/mcp-run-python.svg" alt="license"></a>
  9. <a href="https://logfire.pydantic.dev/docs/join-slack/"><img src="https://img.shields.io/badge/Slack-Join%20Slack-4A154B?logo=slack" alt="Join Slack" /></a>
  10. </div>
  11. <br/>
  12. <div align="center">
  13. MCP server to run Python code in a sandbox.
  14. </div>
  15. <br/>
  16. ---
  17. # NOTICE
  18. We've decided to retire and archive this project - there's just no safe way to run Python within pyodide safely with reasonable latency.
  19. Instead, we're working hard on [Monty](https://github.com/pydantic/monty) which should solve the usecase we initially intended for `mcp-run-python`, with better security, lower latency, easier install, and better ways to communicate with the OS.
  20. If you want to use this projects code, or otherwise use pyodide to run LLM generated code, feel free to do so.
  21. However be extremely careful about how you sandbox the service and what code you allow to run.
  22. In particular **Python code running in pyodide can run arbitrary javascript** meaning it can do whatever the javascript runtime running pydodie can do, including:
  23. * tainting that runtime to control or alter how code runs on later onvocations
  24. * reading and/or writing to any files that runtime has access to
  25. * OOMing the machine by consuming all memory - deno has no good way limit memory usage
  26. These issues are not problems with Pyodide or Deno - they're behaving as advertised, it's just that those tools were not designed as sandboxes to run untrusted code.
  27. ---
  28. Code is executed using [Pyodide](https://pyodide.org) in [Deno](https://deno.com/) and is therefore isolated from
  29. the rest of the operating system.
  30. ## Features
  31. - **Secure Execution**: Run Python code in a sandboxed WebAssembly environment
  32. - **Package Management**: Automatically detects and installs required dependencies
  33. - **Complete Results**: Captures standard output, standard error, and return values
  34. - **Asynchronous Support**: Runs async code properly
  35. - **Error Handling**: Provides detailed error reports for debugging
  36. _(This code was previously part of [Pydantic AI](https://github.com/pydantic/pydantic-ai) but was moved to a separate repo to make it easier to maintain.)_
  37. ## Usage
  38. To use this server, you must have both Python and [Deno](https://deno.com/) installed.
  39. The server can be run with `deno` installed using `uvx`:
  40. ```bash
  41. uvx mcp-run-python [-h] [--version] [--port PORT] [--deps DEPS] {stdio,streamable-http,streamable-http-stateless,example}
  42. ```
  43. where:
  44. - `stdio` runs the server with the
  45. [Stdio MCP transport](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#stdio) — suitable for
  46. running the process as a subprocess locally
  47. - `streamable-http` runs the server with the
  48. [Streamable HTTP MCP transport](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http) -
  49. suitable for running the server as an HTTP server to connect locally or remotely. This supports stateful requests, but
  50. does not require the client to hold a stateful connection like SSE
  51. - `streamable-http-stateless` runs the server with [Streamable HTTP MCP transport](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http) in stateless mode and does not
  52. support server-to-client notifications
  53. - `example` will run a minimal Python script using `numpy`, useful for checking that the package is working, for the code
  54. to run successfully, you'll need to install `numpy` using `uvx mcp-run-python --deps numpy example`
  55. ## Usage with Pydantic AI
  56. Then you can use `mcp-run-python` with Pydantic AI:
  57. ```python
  58. from pydantic_ai import Agent
  59. from pydantic_ai.mcp import MCPServerStdio
  60. from mcp_run_python import deno_args_prepare
  61. import logfire
  62. logfire.configure()
  63. logfire.instrument_mcp()
  64. logfire.instrument_pydantic_ai()
  65. server = MCPServerStdio('uvx', args=['mcp-run-python@latest', 'stdio'], timeout=10)
  66. agent = Agent('claude-3-5-haiku-latest', toolsets=[server])
  67. async def main():
  68. async with agent:
  69. result = await agent.run('How many days between 2000-01-01 and 2025-03-18?')
  70. print(result.output)
  71. #> There are 9,208 days between January 1, 2000, and March 18, 2025.w
  72. if __name__ == '__main__':
  73. import asyncio
  74. asyncio.run(main())
  75. ```
  76. ## Usage in codes as an MCP server
  77. First install the `mcp-run-python` package:
  78. ```bash
  79. pip install mcp-run-python
  80. # or
  81. uv add mcp-run-python
  82. ```
  83. With `mcp-run-python` installed, you can also run deno directly with `prepare_deno_env` or `async_prepare_deno_env`
  84. ```python
  85. from pydantic_ai import Agent
  86. from pydantic_ai.mcp import MCPServerStdio
  87. from mcp_run_python import async_prepare_deno_env
  88. import logfire
  89. logfire.configure()
  90. logfire.instrument_mcp()
  91. logfire.instrument_pydantic_ai()
  92. async def main():
  93. async with async_prepare_deno_env('stdio') as deno_env:
  94. server = MCPServerStdio('deno', args=deno_env.args, cwd=deno_env.cwd, timeout=10)
  95. agent = Agent('claude-3-5-haiku-latest', toolsets=[server])
  96. async with agent:
  97. result = await agent.run('How many days between 2000-01-01 and 2025-03-18?')
  98. print(result.output)
  99. #> There are 9,208 days between January 1, 2000, and March 18, 2025.w
  100. if __name__ == '__main__':
  101. import asyncio
  102. asyncio.run(main())
  103. ```
  104. **Note**: `prepare_deno_env` can take `deps` as a keyword argument to install dependencies.
  105. As well as returning the args needed to run `mcp_run_python`, `prepare_deno_env` creates a new deno environment
  106. and installs the dependencies so they can be used by the server.
  107. ## Usage in code with `code_sandbox`
  108. `mcp-run-python` includes a helper function `code_sandbox` to allow you to easily run code in a sandbox.
  109. ```py
  110. from mcp_run_python import code_sandbox
  111. code = """
  112. import numpy
  113. a = numpy.array([1, 2, 3])
  114. print(a)
  115. a
  116. """
  117. async def main():
  118. async with code_sandbox(dependencies=['numpy']) as sandbox:
  119. result = await sandbox.eval(code)
  120. print(result)
  121. if __name__ == '__main__':
  122. import asyncio
  123. asyncio.run(main())
  124. ```
  125. Under the hood, `code_sandbox` runs an MCP server using `stdio`. You can run multiple code blocks with a single sandbox.
  126. ## Logging
  127. MCP Run Python supports emitting stdout and stderr from the python execution as [MCP logging messages](https://github.com/modelcontextprotocol/specification/blob/eb4abdf2bb91e0d5afd94510741eadd416982350/docs/specification/draft/server/utilities/logging.md?plain=1).
  128. 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`.
  129. ## Dependencies
  130. `mcp_run_python` uses a two step process to install dependencies while avoiding any risk that sandboxed code can
  131. edit the filesystem.
  132. * `deno` is first run with write permissions to the `node_modules` directory and dependencies are installed, causing wheels to be written to ``
  133. * `deno` is then run with read-only permissions to the `node_modules` directory to run untrusted code.
  134. Dependencies must be provided when initializing the server so they can be installed in the first step.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.