Glama
Sign In

MCP Python Toolbox

by gianlucamazza
GitHub
Python
1
  • Linux
  • Apple
RedditDiscord
OverviewInspectSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

local-only server

The server can only run on the client’s local machine because it depends on local resources.

Integrations

  • Provides dependency management for Flask applications, allowing installation and version management of the web framework.

  • Supports running tests for Python projects through the testing framework.

  • Provides comprehensive Python development tools including code analysis, formatting with Black/PEP8, linting with Pylint, project management with virtual environments, dependency handling, and safe code execution capabilities.

MCP Python Toolbox

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
  1. Create and activate a virtual environment:
python -m venv .venv source .venv/bin/activate # Linux/Mac # or .venv\Scripts\activate # Windows
  1. Install the package in development mode:
pip install -e ".[dev]"

Usage

Running as a CLI Tool

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

# Start with current directory as workspace python -m mcp_python_toolbox # Or specify a workspace directory python -m mcp_python_toolbox --workspace /path/to/your/project

Setting Up with Claude Desktop

Claude Desktop can automatically launch and manage the MCP Python Toolbox server. Here's how to configure it:

  1. Install and set up the MCP Python Toolbox as described above
  2. Add a configuration entry for the Python Toolbox in Claude Desktop's MCP tools configuration:
"python-toolbox": { "command": "/Users/username/path/to/mcp_python_toolbox/.venv/bin/python", "args": [ "-m", "mcp_python_toolbox", "--workspace", "/Users/username/path/to/workspace" ], "env": { "PYTHONPATH": "/Users/username/path/to/mcp_python_toolbox/src", "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin", "VIRTUAL_ENV": "/Users/username/path/to/mcp_python_toolbox/.venv", "PYTHONHOME": "" } }
  1. Customize the paths to match your environment
  2. Claude Desktop will automatically start the MCP server when needed
  3. Claude will now have access to Python development tools through the MCP interface

Programmatic Usage

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

Core Module Examples

File Operations

from mcp_python_toolbox.core import FileOperations file_ops = FileOperations(workspace_root="/path/to/project") # Read file contents content = file_ops.read_file("src/example.py") # Read specific lines lines = file_ops.read_file("src/example.py", start_line=10, end_line=20) # Write to file file_ops.write_file("output.txt", "Hello, World!") # Append to file file_ops.write_file("log.txt", "New entry\n", mode='a') # List directory contents contents = file_ops.list_directory("src") for item in contents: print(f"{item['name']} - {item['type']} - {item['size']} bytes")

Code Analysis

from mcp_python_toolbox.core import CodeAnalyzer analyzer = CodeAnalyzer(workspace_root="/path/to/project") # Analyze Python file structure analysis = analyzer.parse_python_file("src/example.py") print(f"Found {len(analysis['functions'])} functions") print(f"Found {len(analysis['classes'])} classes") # Format code formatted = analyzer.format_code(code, style='black') # Lint code issues = analyzer.lint_code("src/example.py") for issue in issues: print(f"Line {issue['line']}: {issue['message']}")

Project Management

from mcp_python_toolbox.core import ProjectManager pm = ProjectManager(workspace_root="/path/to/project") # Create virtual environment pm.create_virtual_environment() # Install dependencies pm.install_dependencies() # from requirements.txt or pyproject.toml pm.install_dependencies("requirements-dev.txt") # from specific file # Check for conflicts conflicts = pm.check_dependency_conflicts() if conflicts: print("Found dependency conflicts:") for conflict in conflicts: print(f"{conflict['package']} requires {conflict['requires']}") # Update packages pm.update_package("requests") # to latest pm.update_package("flask", version="2.0.0") # to specific version

Code Execution

from mcp_python_toolbox.core import CodeExecutor executor = CodeExecutor(workspace_root="/path/to/project") code = ''' def greet(name): return f"Hello, {name}!" print(greet("World")) ''' result = executor.execute_code(code) print(f"Output: {result['stdout']}") print(f"Errors: {result['stderr']}") print(f"Exit code: {result['exit_code']}")

Development

Running Tests

pytest

Type Checking

mypy src/mcp_python_toolbox

Linting

pylint src/mcp_python_toolbox

Formatting

black src/mcp_python_toolbox

Contributing

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

  • Implements the Model Context Protocol specification
  • Built with modern Python development tools and best practices
  • Uses industry-standard formatting (Black) and linting (Pylint) tools

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

A Model Context Protocol server that enables AI assistants like Claude to perform Python development tasks through file operations, code analysis, project management, and safe code execution.

  1. Overview
    1. Features
      1. File Operations (FileOperations)
        1. Code Analysis (CodeAnalyzer)
          1. Project Management (ProjectManager)
            1. Code Execution (CodeExecutor)
            2. Installation
              1. Usage
                1. Running as a CLI Tool
                  1. Setting Up with Claude Desktop
                    1. Programmatic Usage
                      1. Core Module Examples
                        1. File Operations
                          1. Code Analysis
                            1. Project Management
                              1. Code Execution
                            2. Development
                              1. Running Tests
                                1. Type Checking
                                  1. Linting
                                    1. Formatting
                                    2. Contributing
                                      1. License
                                        1. Acknowledgments

                                          Related Resources