Python Toolbox

by gianlucamazza

5 299 downloads Not rated yet MIT

GitHub

About

Integrates Python development tools for file operations, code analysis, project management, and safe code execution, enabling advanced programming workflows and automated testing.

Details

Repository: gianlucamazza/mcp_python_toolbox
License: MIT

Explore

- Safe file operations with workspace path validation
- AST-based Python code analysis (imports, functions, classes)
- Code formatting via Black and PEP8 (autopep8)
- Code linting using Pylint with detailed reports
- Virtual environment creation and dependency management
- Sandboxed code execution using the project’s virtual environment

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below
Plugin Name Python Toolbox

Command (node, npx, python, etc.) /Users/username/path/to/mcp_python_toolbox/.venv/bin/python
Arguments
- Argument 1 -m
- Argument 2 mcp_python_toolbox
- Argument 3 --workspace
- Argument 4 /Users/username/path/to/workspace
Environment
- PATH /opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
- PYTHONHOME
- PYTHONPATH /Users/username/path/to/mcp_python_toolbox/src
- VIRTUAL_ENV /Users/username/path/to/mcp_python_toolbox/.venv
Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "python toolbox": {
            "env": {
                "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin",
                "PYTHONHOME": "",
                "PYTHONPATH": "/Users/username/path/to/mcp_python_toolbox/src",
                "VIRTUAL_ENV": "/Users/username/path/to/mcp_python_toolbox/.venv"
            },
            "args": [
                "-m",
                "mcp_python_toolbox",
                "--workspace",
                "/Users/username/path/to/workspace"
            ],
            "command": "/Users/username/path/to/mcp_python_toolbox/.venv/bin/python"
        }
    }
}

JSON

{
    "mcpServers": {
        "python toolbox": {
            "env": {
                "PATH": "C:\\opt\\homebrew\\bin;C:\\usr\\local\\bin;C:\\usr\\bin;C:\\bin;C:\\usr\\sbin;C:\\sbin",
                "PYTHONHOME": "",
                "PYTHONPATH": "C:\\Users\\username\\path\\to\\mcp_python_toolbox\\src",
                "VIRTUAL_ENV": "C:\\Users\\username\\path\\to\\mcp_python_toolbox\\.venv"
            },
            "args": [
                "-m",
                "mcp_python_toolbox",
                "--workspace",
                "C:\\Users\\username\\path\\to\\workspace"
            ],
            "command": "C:\\Users\\username\\path\\to\\mcp_python_toolbox\\.venv\\Scripts\\python.exe"
        }
    }
}

JSON

{
    "mcpServers": {
        "python toolbox": {
            "env": {
                "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin",
                "PYTHONHOME": "",
                "PYTHONPATH": "/Users/username/path/to/mcp_python_toolbox/src",
                "VIRTUAL_ENV": "/Users/username/path/to/mcp_python_toolbox/.venv"
            },
            "args": [
                "-m",
                "mcp_python_toolbox",
                "--workspace",
                "/Users/username/path/to/workspace"
            ],
            "command": "/Users/username/path/to/mcp_python_toolbox/.venv/bin/python"
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "python toolbox": {
            "env": {
                "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin",
                "PYTHONHOME": "",
                "PYTHONPATH": "/Users/username/path/to/mcp_python_toolbox/src",
                "VIRTUAL_ENV": "/Users/username/path/to/mcp_python_toolbox/.venv"
            },
            "args": [
                "-m",
                "mcp_python_toolbox",
                "--workspace",
                "/Users/username/path/to/workspace"
            ],
            "command": "/Users/username/path/to/mcp_python_toolbox/.venv/bin/python"
        }
    }
}

JSON

{
    "mcpServers": {
        "python toolbox": {
            "env": {
                "PATH": "C:\\opt\\homebrew\\bin;C:\\usr\\local\\bin;C:\\usr\\bin;C:\\bin;C:\\usr\\sbin;C:\\sbin",
                "PYTHONHOME": "",
                "PYTHONPATH": "C:\\Users\\username\\path\\to\\mcp_python_toolbox\\src",
                "VIRTUAL_ENV": "C:\\Users\\username\\path\\to\\mcp_python_toolbox\\.venv"
            },
            "args": [
                "-m",
                "mcp_python_toolbox",
                "--workspace",
                "C:\\Users\\username\\path\\to\\workspace"
            ],
            "command": "C:\\Users\\username\\path\\to\\mcp_python_toolbox\\.venv\\Scripts\\python.exe"
        }
    }
}

JSON

{
    "mcpServers": {
        "python toolbox": {
            "env": {
                "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin",
                "PYTHONHOME": "",
                "PYTHONPATH": "/Users/username/path/to/mcp_python_toolbox/src",
                "VIRTUAL_ENV": "/Users/username/path/to/mcp_python_toolbox/.venv"
            },
            "args": [
                "-m",
                "mcp_python_toolbox",
                "--workspace",
                "/Users/username/path/to/workspace"
            ],
            "command": "/Users/username/path/to/mcp_python_toolbox/.venv/bin/python"
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "python toolbox": {
            "env": {
                "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin",
                "PYTHONHOME": "",
                "PYTHONPATH": "/Users/username/path/to/mcp_python_toolbox/src",
                "VIRTUAL_ENV": "/Users/username/path/to/mcp_python_toolbox/.venv"
            },
            "args": [
                "-m",
                "mcp_python_toolbox",
                "--workspace",
                "/Users/username/path/to/workspace"
            ],
            "command": "/Users/username/path/to/mcp_python_toolbox/.venv/bin/python"
        }
    }
}

JSON

{
    "mcpServers": {
        "python toolbox": {
            "env": {
                "PATH": "C:\\opt\\homebrew\\bin;C:\\usr\\local\\bin;C:\\usr\\bin;C:\\bin;C:\\usr\\sbin;C:\\sbin",
                "PYTHONHOME": "",
                "PYTHONPATH": "C:\\Users\\username\\path\\to\\mcp_python_toolbox\\src",
                "VIRTUAL_ENV": "C:\\Users\\username\\path\\to\\mcp_python_toolbox\\.venv"
            },
            "args": [
                "-m",
                "mcp_python_toolbox",
                "--workspace",
                "C:\\Users\\username\\path\\to\\workspace"
            ],
            "command": "C:\\Users\\username\\path\\to\\mcp_python_toolbox\\.venv\\Scripts\\python.exe"
        }
    }
}

JSON

{
    "mcpServers": {
        "python toolbox": {
            "env": {
                "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin",
                "PYTHONHOME": "",
                "PYTHONPATH": "/Users/username/path/to/mcp_python_toolbox/src",
                "VIRTUAL_ENV": "/Users/username/path/to/mcp_python_toolbox/.venv"
            },
            "args": [
                "-m",
                "mcp_python_toolbox",
                "--workspace",
                "/Users/username/path/to/workspace"
            ],
            "command": "/Users/username/path/to/mcp_python_toolbox/.venv/bin/python"
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "python toolbox": {
            "env": {
                "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin",
                "PYTHONHOME": "",
                "PYTHONPATH": "/Users/username/path/to/mcp_python_toolbox/src",
                "VIRTUAL_ENV": "/Users/username/path/to/mcp_python_toolbox/.venv"
            },
            "args": [
                "-m",
                "mcp_python_toolbox",
                "--workspace",
                "/Users/username/path/to/workspace"
            ],
            "command": "/Users/username/path/to/mcp_python_toolbox/.venv/bin/python"
        }
    }
}

JSON

{
    "mcpServers": {
        "python toolbox": {
            "env": {
                "PATH": "C:\\opt\\homebrew\\bin;C:\\usr\\local\\bin;C:\\usr\\bin;C:\\bin;C:\\usr\\sbin;C:\\sbin",
                "PYTHONHOME": "",
                "PYTHONPATH": "C:\\Users\\username\\path\\to\\mcp_python_toolbox\\src",
                "VIRTUAL_ENV": "C:\\Users\\username\\path\\to\\mcp_python_toolbox\\.venv"
            },
            "args": [
                "-m",
                "mcp_python_toolbox",
                "--workspace",
                "C:\\Users\\username\\path\\to\\workspace"
            ],
            "command": "C:\\Users\\username\\path\\to\\mcp_python_toolbox\\.venv\\Scripts\\python.exe"
        }
    }
}

JSON

{
    "mcpServers": {
        "python toolbox": {
            "env": {
                "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin",
                "PYTHONHOME": "",
                "PYTHONPATH": "/Users/username/path/to/mcp_python_toolbox/src",
                "VIRTUAL_ENV": "/Users/username/path/to/mcp_python_toolbox/.venv"
            },
            "args": [
                "-m",
                "mcp_python_toolbox",
                "--workspace",
                "/Users/username/path/to/workspace"
            ],
            "command": "/Users/username/path/to/mcp_python_toolbox/.venv/bin/python"
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "python toolbox": {
            "env": {
                "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin",
                "PYTHONHOME": "",
                "PYTHONPATH": "/Users/username/path/to/mcp_python_toolbox/src",
                "VIRTUAL_ENV": "/Users/username/path/to/mcp_python_toolbox/.venv"
            },
            "args": [
                "-m",
                "mcp_python_toolbox",
                "--workspace",
                "/Users/username/path/to/workspace"
            ],
            "command": "/Users/username/path/to/mcp_python_toolbox/.venv/bin/python"
        }
    }
}

JSON

{
    "mcpServers": {
        "python toolbox": {
            "env": {
                "PATH": "C:\\opt\\homebrew\\bin;C:\\usr\\local\\bin;C:\\usr\\bin;C:\\bin;C:\\usr\\sbin;C:\\sbin",
                "PYTHONHOME": "",
                "PYTHONPATH": "C:\\Users\\username\\path\\to\\mcp_python_toolbox\\src",
                "VIRTUAL_ENV": "C:\\Users\\username\\path\\to\\mcp_python_toolbox\\.venv"
            },
            "args": [
                "-m",
                "mcp_python_toolbox",
                "--workspace",
                "C:\\Users\\username\\path\\to\\workspace"
            ],
            "command": "C:\\Users\\username\\path\\to\\mcp_python_toolbox\\.venv\\Scripts\\python.exe"
        }
    }
}

JSON

{
    "mcpServers": {
        "python toolbox": {
            "env": {
                "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin",
                "PYTHONHOME": "",
                "PYTHONPATH": "/Users/username/path/to/mcp_python_toolbox/src",
                "VIRTUAL_ENV": "/Users/username/path/to/mcp_python_toolbox/.venv"
            },
            "args": [
                "-m",
                "mcp_python_toolbox",
                "--workspace",
                "/Users/username/path/to/workspace"
            ],
            "command": "/Users/username/path/to/mcp_python_toolbox/.venv/bin/python"
        }
    }
}

From the repository

1. Clone the repository:

git clone https://github.com/gianlucamazza/mcp_python_toolbox.git

cd mcp_python_toolbox

2. Create and activate a virtual environment:

python -m venv .venv source .venv/bin/activate # Linux/Mac The simplest way to start the server is using the CLI:

bash

from mcp_python_toolbox import PythonToolboxServer
server = PythonToolboxServer(workspace_root="/path/to/your/project")

server.setup()

server.run()

pm.create_virtual_environment()

pm.install_dependencies() # from requirements.txt or pyproject.toml
pm.install_dependencies("requirements-dev.txt") # from specific file

pytest

`read_file`

Read the contents of a file. Parameters: file_path (string), start_line (optional int), end_line (optional int)

`write_file`

Write contents to a file. Parameters: file_path (string), content (string), mode (optional string, default is 'w')

`list_directory`

List the contents of a directory. Parameters: directory_path (string)

`parse_python_file`

Parse and analyze the structure of a Python file. Parameters: file_path (string)

`format_code`

Format Python code using specified style. Parameters: code (string), style (string, options include 'black', 'pep8')

`lint_code`

Lint a Python file and return issues found. Parameters: file_path (string)

`create_virtual_environment`

Create a new virtual environment for the project.

`install_dependencies`

Install dependencies from a requirements file or pyproject.toml. Parameters: file_path (optional string)

`check_dependency_conflicts`

Check for conflicts between installed dependencies.

`update_package`

Update a specific package to the latest version or a specified version. Parameters: package_name (string), version (optional string)

`execute_code`

Execute a block of Python code in a controlled environment. Parameters: code (string)

A Model Context Protocol (MCP) server that provides a comprehensive set of tools for Python development, enabling AI assistants like Claude to effectively work with Python code and projects.

The simplest way to start the server is using the CLI:

```bash

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "python toolbox": {
            "env": {
                "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin",
                "PYTHONHOME": "",
                "PYTHONPATH": "/Users/username/path/to/mcp_python_toolbox/src",
                "VIRTUAL_ENV": "/Users/username/path/to/mcp_python_toolbox/.venv"
            },
            "args": [
                "-m",
                "mcp_python_toolbox",
                "--workspace",
                "/Users/username/path/to/workspace"
            ],
            "command": "/Users/username/path/to/mcp_python_toolbox/.venv/bin/python"
        }
    }
}

Linux

{
    "env": {
        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin",
        "PYTHONHOME": "",
        "PYTHONPATH": "/Users/username/path/to/mcp_python_toolbox/src",
        "VIRTUAL_ENV": "/Users/username/path/to/mcp_python_toolbox/.venv"
    },
    "args": [
        "-m",
        "mcp_python_toolbox",
        "--workspace",
        "/Users/username/path/to/workspace"
    ],
    "command": "/Users/username/path/to/mcp_python_toolbox/.venv/bin/python"
}

Macos

{
    "env": {
        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin",
        "PYTHONHOME": "",
        "PYTHONPATH": "/Users/username/path/to/mcp_python_toolbox/src",
        "VIRTUAL_ENV": "/Users/username/path/to/mcp_python_toolbox/.venv"
    },
    "args": [
        "-m",
        "mcp_python_toolbox",
        "--workspace",
        "/Users/username/path/to/workspace"
    ],
    "command": "/Users/username/path/to/mcp_python_toolbox/.venv/bin/python"
}

Windows

{
    "env": {
        "PATH": "C:\\opt\\homebrew\\bin;C:\\usr\\local\\bin;C:\\usr\\bin;C:\\bin;C:\\usr\\sbin;C:\\sbin",
        "PYTHONHOME": "",
        "PYTHONPATH": "C:\\Users\\username\\path\\to\\mcp_python_toolbox\\src",
        "VIRTUAL_ENV": "C:\\Users\\username\\path\\to\\mcp_python_toolbox\\.venv"
    },
    "args": [
        "-m",
        "mcp_python_toolbox",
        "--workspace",
        "C:\\Users\\username\\path\\to\\workspace"
    ],
    "command": "C:\\Users\\username\\path\\to\\mcp_python_toolbox\\.venv\\Scripts\\python.exe"
}

A Model Context Protocol (MCP) server that provides a comprehensive set of tools for Python development, enabling AI assistants like Claude to effectively work with Python code and projects.

Overview

MCP Python Toolbox implements a Model Context Protocol server that gives Claude the ability to perform Python development tasks through a standardized interface. It enables Claude to:

- Read, write, and manage files within a workspace
- Analyze, format, and lint Python code
- Manage virtual environments and dependencies
- Execute Python code safely

Features

File Operations (`FileOperations`)

- Safe file operations within a workspace directory - Path validation to prevent unauthorized access outside workspace - Read and write files with line-specific operations - Create and delete files and directories - List directory contents with detailed metadata (size, type, modification time) - Automatic parent directory creation when writing files

Code Analysis (`CodeAnalyzer`)

- Parse and analyze Python code structure using AST - Extract detailed information about: - Import statements and their aliases - Function definitions with arguments and decorators - Class definitions with base classes and methods - Global variable assignments - Format code using: - Black (default) - PEP8 (using autopep8) - Comprehensive code linting using Pylint with detailed reports

Project Management (`ProjectManager`)

- Create and manage virtual environments with pip support - Flexible dependency management: - Install from requirements.txt - Install from pyproject.toml - Support for specific package versions - Advanced dependency handling: - Check for version conflicts between packages - List all installed packages with versions - Update packages to specific versions - Generate requirements.txt from current environment

Code Execution (`CodeExecutor`)

- Execute Python code in a controlled environment - Uses project's virtual environment for consistent dependencies - Temporary file management for code execution - Capture stdout, stderr, and exit codes - Support for custom working directories

Installation

1. Clone the repository:

git clone https://github.com/gianlucamazza/mcp_python_toolbox.git

cd mcp_python_toolbox

2. Create and activate a virtual environment:
```bash
python -m venv .venv
source .venv/bin/activate # Linux/Mac

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Explore

Setting up with Highlight

From the repository

read_file

write_file

list_directory

parse_python_file

format_code

lint_code

create_virtual_environment

install_dependencies

check_dependency_conflicts

update_package

execute_code

Claude Desktop / Cursor

Linux

Macos

Windows

Overview

Features

File Operations (FileOperations)

Code Analysis (CodeAnalyzer)

Project Management (ProjectManager)

Code Execution (CodeExecutor)

Installation

More like this

Time

Sentry

Github

Git

`read_file`

`write_file`

`list_directory`

`parse_python_file`

`format_code`

`lint_code`

`create_virtual_environment`

`install_dependencies`

`check_dependency_conflicts`

`update_package`

`execute_code`

File Operations (`FileOperations`)

Code Analysis (`CodeAnalyzer`)

Project Management (`ProjectManager`)

Code Execution (`CodeExecutor`)