MCP Python Interpreter MCP Server

How to use

You interact with the MCP Python Interpreter through an MCP client. You can list available Python environments (system and conda), inspect installed packages in a chosen environment, install new packages, run Python code or scripts in a specific environment, and perform file operations such as reading or writing files. Use dedicated prompts to generate Python functions, refactor code, or debug errors. Everything is scoped to a defined working directory to keep actions isolated and secure.

How to install

Prerequisites: you need Python installed on your system and a runtime to host the MCP server. You also need the MCP runtime tool for launching the server.

# Install the MCP Python Interpreter via pip
pip install mcp-python-interpreter

# Or install via uv (recommended for MCP workflow integration)
uv install mcp-python-interpreter

Additional configuration and setup

When you run the MCP server, you provide a working directory where all files will be saved and executed. This directory keeps the server actions isolated for security.

{
  "mcpServers": {
    "mcp-python-interpreter": {
      "command": "uvx",
      "args": [
        "mcp-python-interpreter",
        "--dir",
        "/path/to/your/work/dir",
        "--python-path",
        "/path/to/your/python"
      ],
      "env": {
        "MCP_ALLOW_SYSTEM_ACCESS": 0
      }
    }
  }
}

Windows configuration example

If you are configuring on Windows, the same pattern applies with Windows paths.

{
  "mcpServers": {
    "python-interpreter": {
      "command": "uvx",
      "args": [
        "mcp-python-interpreter",
        "--dir",
        "C:\\path\\to\\your\\working\\directory",
        "--python-path",
        "/path/to/your/python"
      ],
      "env": {
        "MCP_ALLOW_SYSTEM_ACCESS": "0"
      }
    }
  }
}

Notes on usage with a client

To connect your MCP client, load the configured MCP server and start the session. Use the available tools to list environments, manage packages, run code, and perform file operations. Always run within the specified working directory to maintain security boundaries.

Security considerations

This MCP server operates with access to your Python environments and file system within a defined working directory. It enforces strict file path boundaries, applies size limits to read/write operations, and requires explicit overwrite protection to prevent unintended changes. Treat code execution and file operations with caution, especially when running user-provided input.

Examples

Example tasks you can perform with this MCP server include listing environments, running a Python snippet in a chosen environment, creating a new Python file, reading a JSON configuration, listing packages, installing a package, and executing a Python file with arguments.

list_python_environments

List all available Python environments (system and conda)

list_installed_packages

List packages installed in a specific environment

install_package

Install a Python package in a specific environment

run_python_code

Execute Python code in a specific environment

run_python_file

Execute a Python file in a specific environment

read_file

Read contents of any file type, with size and safety limits

write_file

Create or overwrite files with text or binary content

write_python_file

Create or overwrite a Python file specifically

list_directory

List Python files in a directory

python_function_template

Generate a template for a Python function

refactor_python_code

Help refactor Python code

debug_python_error

Help debug a Python error