MCP Run Python Code

🚀 mcp-run-python-code

A Python interpreter on the MCP server, no API key required, and free of charge. Get results from running Python code.

🚀 Quick Start

This MCP server offers 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.
• Provide error handling and debugging support.

📦 Installation

From pip

You can install the MCP Run Python Code Server using uv:

uv pip install mcp-run-python-code

Or using pip:

pip install mcp-run-python-code

From source

git clone https://github.com/shibing624/mcp-run-python-code.git
cd mcp-run-python-code
pip install -e .

💻 Usage Examples

Basic Usage

from run_python_code import RunPythonCode

tool = RunPythonCode(base_dir='/tmp/tmp_run_code/')

# Example 1: Basic code execution
result = tool.run_python_code("x = 10\ny = 20\nz = x * y", "z")
print(f"Result: {result}")  # Output: Result: 200

# Example 2: Save and run a file
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: {result}")  # Output: Result: 20

# Example 3: Install a Python package
result = tool.pip_install_package("requests")
print(f"Result: {result}")

Advanced Usage

Running as a standalone MCP server

Run the server with the stdio transport:

uvx mcp-run-python-code

or

uv run mcp-run-python-code

or

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 the command:

uvx mcp-run-python-code

Available Tools

• 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.

📚 Documentation

Example 1: Basic Code Execution

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 a Python File

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

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:
• Email: xuming624@qq.com
• WeChat: Add me (WeChat ID: xuming624) with the message: "Name-Company-NLP" to join our NLP discussion group.

📄 License

This project is licensed under The Apache License 2.0 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