mcp-python/README.md

MCP Python Project Manager Server

A Model Context Protocol (MCP) server for managing and debugging Python projects on Windows 11.

🚀 Features

Project Management

• Project Info: Get comprehensive information about Python projects including structure, dependencies, and environment
• File Operations: List, read, and analyze project files with filtering options
• Directory Tree: Visualize project structure with configurable depth

Execution & Debugging

• Run Scripts: Execute Python scripts with custom arguments and environment variables
• Debug Info: Get information about running Python processes and scripts
• Environment Details: Inspect Python interpreter, packages, and sys.path

Package Management

• Install Packages: Install packages via pip with requirements file support
• List Packages: View installed packages in JSON or text format
• Dependency Analysis: Analyze requirements files and detect potential issues

Code Quality

• Linting: Run flake8, pylint, and black checks on your code
• Formatting: Auto-format code using black or autopep8
• Testing: Execute tests with pytest or unittest framework

Environment Management

• Virtual Environments: Create and manage Python virtual environments
• Environment Detection: Auto-detect and use project venvs
• Python Version Support: Configure specific Python versions

File Watching

• Change Notifications: Watch files for modifications (configurable patterns)
• Pattern Filtering: Include/exclude files by glob patterns

📦 Installation

Prerequisites

Option A: Using uv (Recommended ⚡)

• uv installed on Windows 11
• Install uv: winget install astral-sh.uv or pip install uv

Option B: Traditional Python

• Python 3.10+ installed on Windows 11
• pip package manager

Setup with uv (Recommended)

# 1. Navigate to project directory
cd C:\Users\dimir\proects\mcp-python

# 2. Install and run directly with uvx (no venv needed!)
uvx --from C:/Users/dimir/proects/mcp-python mcp-python-manager

Setup with pip (Traditional)

# 1. Clone or create project directory:
cd C:\Users\dimir\proects
mkdir mcp-python
cd mcp-python

# 2. Create virtual environment:
python -m venv .venv
.venv\Scripts\activate

# 3. Install dependencies:
pip install -r requirements.txt

# 4. Optional: Install development tools:
pip install py-spy safety pip-audit

⚙️ Configuration

Environment Variables

Variable	Description	Default
MCP_PYTHON_WORKSPACE	Root directory for projects	C:/Users/dimir/projects
MCP_PYTHON_DEBUG	Enable debug logging	false
MCP_PYTHON_LOG_LEVEL	Logging level	INFO
MCP_PYTHON_MAX_EXEC_TIME	Command timeout (seconds)	300

Config File (config.py)

Customize server behavior by editing config.py:

from config import ServerConfig

config = ServerConfig(
    workspace_root=Path("C:/Users/dimir/projects"),
    venv_name=".venv",
    debug_mode=True,
    allowed_commands=["python", "pip", "pytest", "black", "flake8", "pylint"],
    max_execution_time=600,
)

🔌 Usage

Running the Server

🚀 With uvx (Recommended)

# Run directly without installation
uvx --from C:/Users/dimir/proects/mcp-python mcp-python-manager

# With custom workspace
uvx --from C:/Users/dimir/proects/mcp-python mcp-python-manager --workspace "C:\MyProjects"

# With debug mode
uvx --from C:/Users/dimir/proects/mcp-python mcp-python-manager --debug

# SSE transport
uvx --from C:/Users/dimir/proects/mcp-python mcp-python-manager --transport sse --port 8000

🐍 With Python (Traditional)

Stdio Transport (Default for MCP clients):

# Direct execution
python server.py

# Via MCP stdio module
python -m mcp.server.stdio server:main

SSE Transport (HTTP-based clients):

python server.py --transport sse --host localhost --port 8000

With Options:

python server.py --debug --workspace "C:\MyProjects"

Connecting from Claude Desktop

⚡ Using uvx (Recommended)

Add to your Claude Desktop config (%APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "python-manager": {
      "command": "uvx",
      "args": [
        "--from",
        "C:/Users/dimir/proects/mcp-python",
        "mcp-python-manager",
        "--transport",
        "stdio"
      ],
      "env": {
        "MCP_PYTHON_WORKSPACE": "C:/Users/dimir/projects",
        "UV_NO_CACHE": "0",
        "UV_LINK_MODE": "copy"
      }
    }
  }
}

🐍 Using Python (Traditional)

{
  "mcpServers": {
    "python-manager": {
      "command": "python",
      "args": [
        "C:/Users/dimir/proects/mcp-python/server.py"
      ],
      "env": {
        "MCP_PYTHON_WORKSPACE": "C:/Users/dimir/projects"
      }
    }
  }
}

Connecting from Cursor/VS Code

⚡ Using uvx (Recommended)

{
  "mcp": {
    "servers": {
      "python-manager": {
        "type": "stdio",
        "command": "uvx",
        "args": [
          "--from",
          "C:/Users/dimir/proects/mcp-python",
          "mcp-python-manager",
          "--transport",
          "stdio"
        ],
        "env": {
          "UV_NO_CACHE": "0",
          "UV_LINK_MODE": "copy"
        }
      }
    }
  }
}

🐍 Using Python (Traditional)

{
  "mcp": {
    "servers": {
      "python-manager": {
        "type": "stdio",
        "command": "python",
        "args": ["C:/Users/dimir/proects/mcp-python/server.py"],
        "env": {
          "PYTHONUNBUFFERED": "1"
        }
      }
    }
  }
}

🛠️ Available Tools

get_project_info

Get comprehensive project information.

{
  "project_path": "C:/Users/dimir/projects/my-app"
}

run_python_script

Execute a Python script.

{
  "script_path": "main.py",
  "args": ["--config", "prod.yaml"],
  "env": {"DEBUG": "false"},
  "use_venv": true,
  "cwd": "C:/Users/dimir/projects/my-app"
}

install_package

Install Python packages.

{
  "packages": ["requests", "fastapi"],
  "upgrade": true,
  "use_venv": true
}

Or with requirements file:

{
  "requirements_file": "requirements.txt",
  "use_venv": true
}

list_packages

List installed packages.

{
  "project_path": "C:/Users/dimir/projects/my-app",
  "format": "json"
}

run_tests

Execute tests.

{
  "test_path": "tests/",
  "test_framework": "pytest",
  "args": ["-x", "--cov"],
  "verbose": true
}

lint_code

Run code linters.

{
  "file_path": "src/",
  "linter": "all",
  "fix": false
}

create_venv

Create virtual environment.

{
  "project_path": "C:/Users/dimir/projects/new-project",
  "venv_name": ".venv",
  "python_version": "3.11"
}

get_debug_info

Get debugging information.

{
  "script_path": "main.py",
  "include_stack": true
}

Or by PID:

{
  "pid": 12345,
  "include_stack": true
}

list_project_files

List project files.

{
  "directory": "C:/Users/dimir/projects/my-app",
  "pattern": "*.py",
  "recursive": true,
  "exclude_dirs": ["__pycache__", ".git"]
}

read_file

Read file contents.

{
  "file_path": "main.py",
  "start_line": 1,
  "end_line": 50,
  "encoding": "utf-8"
}

execute_command

Execute allowed shell commands.

{
  "command": "python -m pytest tests/ -v",
  "cwd": "C:/Users/dimir/projects/my-app",
  "timeout": 120
}

get_python_env

Get Python environment info.

{
  "project_path": "C:/Users/dimir/projects/my-app"
}

format_code

Format Python code.

{
  "file_path": "src/",
  "formatter": "black",
  "check_only": false
}

analyze_dependencies

Analyze project dependencies.

{
  "project_path": "C:/Users/dimir/projects/my-app",
  "check_updates": false,
  "check_security": false
}

watch_files

Configure file watching.

{
  "directory": "C:/Users/dimir/projects/my-app/src",
  "patterns": ["*.py", "*.json"],
  "recursive": true
}

🔒 Security

Allowed Commands

By default, only these commands can be executed:

• python - Run Python scripts
• pip - Package management
• pytest - Run tests
• black - Code formatting
• flake8 - Linting
• pylint - Advanced linting

Modify config.allowed_commands to customize.

Path Validation

All file paths are validated to prevent directory traversal attacks.

Output Truncation

Command output is limited to max_output_length characters (default: 50,000).

🐛 Debugging

Enable Debug Logging

set MCP_PYTHON_DEBUG=true
set MCP_PYTHON_LOG_LEVEL=DEBUG
python server.py

Log File

Configure logging to file in config.py:

config.log_file = Path("C:/Users/dimir/proects/mcp-python/server.log")

Common Issues

Issue	Solution
"Command not allowed"	Add command to config.allowed_commands
"Virtual environment not found"	Create venv with create_venv tool or manually
"Timeout executing command"	Increase max_execution_time in config
"Permission denied"	Run terminal as Administrator or check file permissions

🧪 Testing the Server

Manual Test with MCP Inspector

# Install MCP inspector
npm install -g @modelcontextprotocol/inspector

# Run server and inspector
python server.py
# In another terminal:
mcp-inspector

Python Test Script

import asyncio
from mcp.client.session import ClientSession
from mcp.client.stdio import stdio_client

async def test_server():
    async with stdio_client(["python", "server.py"]) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            
            # List available tools
            tools = await session.list_tools()
            print(f"Available tools: {[t.name for t in tools.tools]}")
            
            # Test get_project_info
            result = await session.call_tool(
                "get_project_info",
                {"project_path": "C:/Users/dimir/projects"}
            )
            print(result)

asyncio.run(test_server())

📁 Project Structure

mcp-python/
├── server.py           # Main server entry point
├── tools.py            # MCP tool implementations
├── config.py           # Configuration settings
├── requirements.txt    # Python dependencies
├── README.md          # This file
├── .gitignore         # Git ignore rules
└── logs/              # Log files (created at runtime)

🔄 Development

Adding New Tools

1. Add tool definition in tools.py _register_tools() method
2. Implement the async method in PythonProjectTools class
3. Add handler case in handle_tool_call() method
4. Update this README with documentation

Example Tool Addition

# In _register_tools():
Tool(
    name="my_new_tool",
    description="What this tool does",
    inputSchema={...}
)

# Implementation:
async def my_new_tool(self, arg1: str) -> ToolResult:
    # Your logic here
    return ToolResult(success=True, message="Done", data={...})

# Handler:
elif name == "my_new_tool":
    result = await self.my_new_tool(**arguments)

📄 License

MIT License - Feel free to use and modify for your projects.

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

🔗 Resources

• MCP Specification
• MCP Python SDK
• Windows Python Setup Guide

---

Author: dimir
Created: 2026
Platform: Windows 11, Python 3.10+