Python MCP Server

Python MCP Server

A Model Context Protocol (MCP) server for executing Python code and managing Python environments. This server allows Claude and other LLMs to run Python code, manage files, and work with Python packages.

Features

• Code Execution: Run Python code snippets or execute Python files
• File Management: List, read, and write Python files
• Python Environment: Check Python version and environment details
• Configurable Execution: Set timeouts, working directories, and command-line arguments

Prerequisites

Before using this MCP server, ensure you have:

• Node.js 22 or higher installed
• Python installed and available in your PATH
• Claude Desktop or Cline installed

Installation

1. Clone this repository:

git clone https://github.com/Timtech4u/python-mcp-server.git
cd python-mcp-server

2. Install dependencies:

npm ci

3. Build the project:

npm run build

Configuration

For Claude Desktop

1. Open your Claude Desktop configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the Python MCP server configuration:

{
  "mcpServers": {
    "python": {
      "command": "node",
      "args": [
        "/absolute/path/to/python-mcp-server/dist/index.js"
      ],
      "disabled": false,
      "autoApprove": [
        "execute_python_code",
        "execute_python_file",
        "check_python_version",
        "list_python_files",
        "read_python_file",
        "write_python_file"
      ]
    }
  }
}

3. Replace /absolute/path/to/python-mcp-server with the actual path where you cloned the repository.

4. Restart Claude Desktop.

For Cline

1. Open your Cline MCP settings file:

   • macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
   • Windows: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

2. Add the Python MCP server configuration:

{
  "mcpServers": {
    "python": {
      "command": "node",
      "args": [
        "/absolute/path/to/python-mcp-server/dist/index.js"
      ],
      "disabled": false,
      "autoApprove": [
        "execute_python_code",
        "execute_python_file",
        "check_python_version",
        "list_python_files",
        "read_python_file",
        "write_python_file"
      ]
    }
  }
}

3. Replace /absolute/path/to/python-mcp-server with the actual path where you cloned the repository.

4. Restart Cline or reload the window.

How to Use

Once configured, you can ask Claude to run Python code in various ways. Here are some examples:

Execute Python Code

Can you run this Python code for me?

import random
numbers = [random.randint(1, 100) for _ in range(10)]
print(f"Random numbers: {numbers}")
print(f"Sum: {sum(numbers)}")
print(f"Average: {sum(numbers)/len(numbers)}")

Execute a Python File

Can you execute my Python file at /path/to/my_script.py?

List Python Files

Can you list all Python files in my /path/to/project directory?

Read a Python File

Can you show me the contents of /path/to/my_script.py?

Write a Python File

Can you create a Python file at /path/to/new_script.py with the following content?

def hello_world():
    print("Hello, world!")

if __name__ == "__main__":
    hello_world()

Check Python Version

What version of Python do I have installed?

Available Tools

execute_python_code

Executes Python code snippets.

Parameters:

• code (string, required): The Python code to execute
• timeout (number, optional): Maximum execution time in seconds (default: 30)
• args (array of strings, optional): Command line arguments to pass to the script
• workingDir (string, optional): Working directory for the script execution

execute_python_file

Executes a Python file.

Parameters:

• filePath (string, required): Path to the Python file to execute
• timeout (number, optional): Maximum execution time in seconds (default: 30)
• args (array of strings, optional): Command line arguments to pass to the script
• workingDir (string, optional): Working directory for the script execution

check_python_version

Returns information about the installed Python version.

list_python_files

Lists Python files in a directory.

Parameters:

• dirPath (string, optional): Directory path to list Python files from (default: current directory)
• recursive (boolean, optional): Whether to search recursively (default: false)

read_python_file

Reads the content of a Python file.

Parameters:

• filePath (string, required): Path to the Python file to read

write_python_file

Writes content to a Python file.

Parameters:

• filePath (string, required): Path to the Python file to write
• content (string, required): Content to write to the file
• createDirs (boolean, optional): Create directories if they do not exist (default: true)

Troubleshooting

Python Not Found

If you see an error like "Python is not installed", make sure Python is installed and available in your system PATH.

Permission Errors

If you encounter permission errors when reading or writing files, make sure the user running the MCP server has the necessary permissions.

Timeout Errors

The server has a default 30-second timeout for code execution. If your code takes longer than that, it will be terminated. You can increase the timeout by specifying the timeout parameter.

License

MIT

Verification

Use Node.js 22+ and a Python 3 executable on PATH:

npm ci
npm test
npm audit

The integration test starts the actual stdio server, negotiates an MCP session, checks tool discovery, executes Python, and verifies file read/write/list behavior inside a temporary directory. SDK and UUID versions are pinned in both dependency files; the UUID package now supplies its own TypeScript declarations.