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
- Clone the repository:
git clone https://github.com/gianlucamazza/mcp_python_toolbox.git
cd mcp_python_toolbox
- Create and activate a virtual environment:
python -m venv .venv
source .venv/bin/activate # Linux/Mac
# or
.venv\Scripts\activate # Windows
- 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:
- Install and set up the MCP Python Toolbox as described above
- 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": ""
}
}
- Customize the paths to match your environment
- Claude Desktop will automatically start the MCP server when needed
- 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
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - 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