# mcp-run-python-code
Python interpreter, MCP server, no API key, free. Get results from running Python code.
## Overview
This MCP server provides tools for running Python code, installing packages, and executing Python files.
It can be easily integrated with MCP clients, including Claude and other LLM applications supporting the MCP protocol.
## Features
- Execute Python code in a safe environment
- Install Python packages using pip
- Save Python code to files and run them
- Run existing Python files
- Return specific variable values from executed code
- Error handling and debugging support
## Installation
### From pip
You can install the MCP Run Python Code Server using `uv`:
```bash
uv pip install mcp-run-python-code
```
Or using pip:
```bash
pip install mcp-run-python-code
```
### From source
```bash
git clone https://github.com/shibing624/mcp-run-python-code.git
cd mcp-run-python-code
pip install -e .
```
## Usage
### Python Demo
```python
from run_python_code import RunPythonCode
tool = RunPythonCode(base_dir='/tmp/tmp_run_code/')
# 示例1：基本代码执行
result = tool.run_python_code("x = 10\ny = 20\nz = x * y", "z")
print(f"结果: {result}") # 输出: 结果: 200
# 示例2：保存并运行文件
result = tool.save_to_file_and_run(
file_name="calc.py",
code="a = 5\nb = 15\nc = a + b",
variable_to_return="c"
)
print(f"结果: {result}") # 输出: 结果: 20
# 实例3：安装python包
result = tool.pip_install_package("requests")
print(f"结果: {result}")
```
### Running as a standalone MCP server
Run the server with the stdio transport:
```bash
uvx mcp-run-python-code
```
or
```bash
uv run mcp-run-python-code
```
or
```bash
python -m mcp-run-python-code
```
Then, you can use the server with any MCP client that supports stdio transport.
### Integrating with Cursor
To add the weather MCP server to Cursor, add stdio MCP with command:
```bash
uvx mcp-run-python-code
```
### Tools available
- `run_python_code` - Execute Python code and optionally return a variable value
- `save_to_file_and_run` - Save Python code to a file and execute it
- `pip_install_package` - Install Python packages using pip
- `run_python_file` - Run an existing Python file and optionally return a variable value
## Examples
#### Example 1: Basic Code Execution
```python
from run_python_code import RunPythonCode
tool = RunPythonCode(base_dir='/tmp/tmp_run_code/')
# Execute simple calculations
code = "result = 2 ** 10"
value = tool.run_python_code(code, "result")
print(value) # Output: 1024
```
#### Example 2: Run python File
```python
from run_python_code import RunPythonCode
tool = RunPythonCode(base_dir='/tmp/tmp_run_code/')
# Save code to a file and run it
script_code = """
def fibonacci(n):
if n <= 1:
return n
return fibonacci(n-1) + fibonacci(n-2)
result = fibonacci(10)
print(f"Fibonacci(10) = {result}")
"""
result = tool.save_to_file_and_run("fib.py", script_code, "result")
print(result) # Output: 55
```
#### Example 3: Data Processing
```python
from run_python_code import RunPythonCode
tool = RunPythonCode(base_dir='/tmp/tmp_run_code/')
# JSON data processing
code = """
import json
data = {'name': '张三', 'age': 30}
json_str = json.dumps(data, ensure_ascii=False)
"""
result = tool.run_python_code(code, "json_str")
print(result) # Output: {"name": "张三", "age": 30}
```
## Contact
- Issues and suggestions: [](https://github.com/shibing624/mcp-run-python-code/issues)
- Email: xuming624@qq.com
- WeChat: Add me (WeChat ID: xuming624) with the message: "Name-Company-NLP" to join our NLP discussion group.
<img src="https://github.com/shibing624/weather-forecast-server/blob/main/docs/wechat.jpeg" width="200" />
## License
This project is licensed under [The Apache License 2.0](/LICENSE) and can be used freely for commercial purposes.
Please include a link to the `mcp-run-python-code` project and the license in your product description.
## Contribute
We welcome contributions to improve this project! Before submitting a pull request, please:
1. Add appropriate unit tests in the `tests` directory
2. Run `python -m pytest` to ensure all tests pass
3. Submit your PR with clear descriptions of the changes
## Acknowledgements
- Built with [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
Raw data
{
"_id": null,
"home_page": "https://github.com/shibing624/mcp-run-python-code",
"name": "mcp-run-python-code",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "python-interpreter, mcp, run-python-code, install-python-package, execute-python-file",
"author": "XuMing",
"author_email": "xuming624@qq.com",
"download_url": "https://files.pythonhosted.org/packages/15/8d/fcfd08bb9863873045aedca205bde1d8cf32bdad2d6b9e9fad21652e0d00/mcp_run_python_code-0.0.2.tar.gz",
"platform": null,
"description": "# mcp-run-python-code\nPython interpreter, MCP server, no API key, free. Get results from running Python code.\n\n## Overview\n\nThis MCP server provides tools for running Python code, installing packages, and executing Python files. \nIt can be easily integrated with MCP clients, including Claude and other LLM applications supporting the MCP protocol.\n\n## Features\n\n- Execute Python code in a safe environment\n- Install Python packages using pip\n- Save Python code to files and run them\n- Run existing Python files\n- Return specific variable values from executed code\n- Error handling and debugging support\n\n## Installation\n\n### From pip\nYou can install the MCP Run Python Code Server using `uv`:\n\n```bash\nuv pip install mcp-run-python-code\n```\n\nOr using pip:\n\n```bash\npip install mcp-run-python-code\n```\n\n### From source\n```bash\ngit clone https://github.com/shibing624/mcp-run-python-code.git\ncd mcp-run-python-code\npip install -e .\n```\n\n## Usage\n### Python Demo\n```python\nfrom run_python_code import RunPythonCode\n\ntool = RunPythonCode(base_dir='/tmp/tmp_run_code/')\n\n# \u793a\u4f8b1\uff1a\u57fa\u672c\u4ee3\u7801\u6267\u884c\nresult = tool.run_python_code(\"x = 10\\ny = 20\\nz = x * y\", \"z\")\nprint(f\"\u7ed3\u679c: {result}\") # \u8f93\u51fa: \u7ed3\u679c: 200\n\n# \u793a\u4f8b2\uff1a\u4fdd\u5b58\u5e76\u8fd0\u884c\u6587\u4ef6\nresult = tool.save_to_file_and_run(\n file_name=\"calc.py\",\n code=\"a = 5\\nb = 15\\nc = a + b\",\n variable_to_return=\"c\"\n)\nprint(f\"\u7ed3\u679c: {result}\") # \u8f93\u51fa: \u7ed3\u679c: 20\n\n# \u5b9e\u4f8b3\uff1a\u5b89\u88c5python\u5305\nresult = tool.pip_install_package(\"requests\")\nprint(f\"\u7ed3\u679c: {result}\")\n```\n\n\n\n### Running as a standalone MCP server\n\nRun the server with the stdio transport:\n\n```bash\nuvx mcp-run-python-code\n```\n\nor\n\n```bash\nuv run mcp-run-python-code\n```\n\nor \n\n```bash\npython -m mcp-run-python-code\n```\n\nThen, you can use the server with any MCP client that supports stdio transport.\n\n### Integrating with Cursor\n\nTo add the weather MCP server to Cursor, add stdio MCP with command:\n\n```bash\nuvx mcp-run-python-code\n```\n\n### Tools available\n\n- `run_python_code` - Execute Python code and optionally return a variable value\n- `save_to_file_and_run` - Save Python code to a file and execute it\n- `pip_install_package` - Install Python packages using pip\n- `run_python_file` - Run an existing Python file and optionally return a variable value\n\n## Examples\n\n#### Example 1: Basic Code Execution\n```python\nfrom run_python_code import RunPythonCode\ntool = RunPythonCode(base_dir='/tmp/tmp_run_code/')\n# Execute simple calculations\ncode = \"result = 2 ** 10\"\nvalue = tool.run_python_code(code, \"result\")\nprint(value) # Output: 1024\n```\n\n#### Example 2: Run python File\n```python\nfrom run_python_code import RunPythonCode\ntool = RunPythonCode(base_dir='/tmp/tmp_run_code/')\n# Save code to a file and run it\nscript_code = \"\"\"\ndef fibonacci(n):\n if n <= 1:\n return n\n return fibonacci(n-1) + fibonacci(n-2)\n\nresult = fibonacci(10)\nprint(f\"Fibonacci(10) = {result}\")\n\"\"\"\nresult = tool.save_to_file_and_run(\"fib.py\", script_code, \"result\")\nprint(result) # Output: 55\n```\n\n#### Example 3: Data Processing\n```python\nfrom run_python_code import RunPythonCode\ntool = RunPythonCode(base_dir='/tmp/tmp_run_code/')\n# JSON data processing\ncode = \"\"\"\nimport json\ndata = {'name': '\u5f20\u4e09', 'age': 30}\njson_str = json.dumps(data, ensure_ascii=False)\n\"\"\"\nresult = tool.run_python_code(code, \"json_str\")\nprint(result) # Output: {\"name\": \"\u5f20\u4e09\", \"age\": 30}\n```\n\n\n## Contact\n\n- Issues and suggestions: [](https://github.com/shibing624/mcp-run-python-code/issues)\n- Email: xuming624@qq.com\n- WeChat: Add me (WeChat ID: xuming624) with the message: \"Name-Company-NLP\" to join our NLP discussion group.\n\n<img src=\"https://github.com/shibing624/weather-forecast-server/blob/main/docs/wechat.jpeg\" width=\"200\" />\n\n\n## License\n\nThis project is licensed under [The Apache License 2.0](/LICENSE) and can be used freely for commercial purposes. \nPlease include a link to the `mcp-run-python-code` project and the license in your product description.\n## Contribute\n\nWe welcome contributions to improve this project! Before submitting a pull request, please:\n\n1. Add appropriate unit tests in the `tests` directory\n2. Run `python -m pytest` to ensure all tests pass\n3. Submit your PR with clear descriptions of the changes\n\n## Acknowledgements\n\n- Built with [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) \n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "mcp-run-python-code: MCP server for running Python code, installing packages, and executing Python files.",
"version": "0.0.2",
"project_urls": {
"Homepage": "https://github.com/shibing624/mcp-run-python-code"
},
"split_keywords": [
"python-interpreter",
" mcp",
" run-python-code",
" install-python-package",
" execute-python-file"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "158dfcfd08bb9863873045aedca205bde1d8cf32bdad2d6b9e9fad21652e0d00",
"md5": "14df22feba2b08e253633a98ed1ece3e",
"sha256": "adcfca6a41b71fd13a7dc26a6d890de4490d0fa8c8c1593a8e60f18960593dba"
},
"downloads": -1,
"filename": "mcp_run_python_code-0.0.2.tar.gz",
"has_sig": false,
"md5_digest": "14df22feba2b08e253633a98ed1ece3e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 11459,
"upload_time": "2025-08-14T09:25:05",
"upload_time_iso_8601": "2025-08-14T09:25:05.973861Z",
"url": "https://files.pythonhosted.org/packages/15/8d/fcfd08bb9863873045aedca205bde1d8cf32bdad2d6b9e9fad21652e0d00/mcp_run_python_code-0.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-14 09:25:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "shibing624",
"github_project": "mcp-run-python-code",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "mcp",
"specs": []
},
{
"name": "requests",
"specs": []
},
{
"name": "loguru",
"specs": []
}
],
"lcname": "mcp-run-python-code"
}
JSON
