mcp-python/QUICKSTART.md

🚀 Quick Start Guide

⚡ First Time Setup with uv (Recommended)

# 1. Install uv if not already installed
winget install astral-sh.uv
# or
pip install uv

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

# 3. Run directly with uvx - no setup needed!
uvx --from . mcp-python-manager

🐍 First Time Setup with pip (Traditional)

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

# 2. Create virtual environment
python -m venv .venv

# 3. Activate virtual environment
.venv\Scripts\activate

# 4. Install dependencies
pip install -r requirements.txt

# 5. (Optional) Install dev tools
pip install -e ".[dev]"

Run the Server

⚡ With uvx (Recommended)

# Basic run (stdio transport - for MCP clients)
uvx --from . mcp-python-manager

# With debug output
uvx --from . mcp-python-manager --debug

# With custom workspace
uvx --from . mcp-python-manager --workspace "C:\My\Projects"

# SSE transport (for HTTP clients)
uvx --from . mcp-python-manager --transport sse --port 8000

🐍 With Python (Traditional)

# Basic run (stdio transport - for MCP clients)
python server.py

# With debug output
python server.py --debug

# With custom workspace
python server.py --workspace "C:\My\Projects"

# SSE transport (for HTTP clients)
python server.py --transport sse --port 8000

Test the Server

# Run built-in tests
python test_server.py

# Run with pytest (if installed)
pytest tests/ -v

Connect from Claude Desktop

⚡ Using uvx (Recommended)

1. Edit your Claude Desktop config:

   • Location: %APPDATA%\Claude\claude_desktop_config.json

2. Add this configuration:

{
  "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"
      }
    }
  }
}

3. Restart Claude Desktop

🐍 Using Python (Traditional)

1. Edit your Claude Desktop config:

   • Location: %APPDATA%\Claude\claude_desktop_config.json

2. Add this configuration:

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

3. Restart Claude Desktop

Example Prompts for Claude

Once connected, you can ask Claude to:

📁 Project Management:
- "Show me the structure of my project at C:\projects\myapp"
- "What Python files are in the src directory?"
- "Read the first 50 lines of main.py"

🔧 Code Execution:
- "Run the script at scripts/deploy.py with --dry-run argument"
- "Execute pytest on the tests folder with coverage"
- "Install the packages from requirements.txt"

🐛 Debugging:
- "What Python processes are currently running?"
- "Get debug info for main.py"
- "Show me the Python environment details"

✨ Code Quality:
- "Lint all Python files in src/ using flake8"
- "Format the code in utils.py using black"
- "Run pylint on the entire project"

📦 Dependencies:
- "List all installed packages in my venv"
- "Analyze dependencies in requirements.txt for issues"
- "Create a new virtual environment for my project"

Common Commands Reference

⚡ With uvx

Task	Command
Start server	uvx --from . mcp-python-manager
Start with debug	uvx --from . mcp-python-manager --debug
Start with workspace	uvx --from . mcp-python-manager --workspace "C:\Projects"
Install uv	winget install astral-sh.uv
Update uv	uv self update

🐍 With pip

Task	Command
Start server	python server.py
Test server	python test_server.py
Install deps	pip install -r requirements.txt
Install dev deps	pip install -e ".[dev]"
Run with debug	python server.py --debug
Check Python version	python --version
Activate venv	.venv\Scripts\activate
Deactivate venv	deactivate

Troubleshooting

Server won't start

# Check Python version
python --version  # Should be 3.10+

# Reinstall dependencies
pip install --upgrade -r requirements.txt

# Check for port conflicts (SSE mode)
netstat -ano | findstr :8000

Tools not working

# Enable debug logging
set MCP_PYTHON_DEBUG=true
python server.py

# Check allowed commands in config.py
# Add missing commands to config.allowed_commands

Permission errors

# Run terminal as Administrator
# Or adjust file/folder permissions
# Check antivirus software blocking execution

Next Steps

1. ✅ Server installed and tested
2. ⬜ Configure Claude Desktop / Cursor / VS Code
3. ⬜ Customize config.py for your workflow
4. ⬜ Add custom tools in tools.py
5. ⬜ Set up CI/CD for your projects

Need Help?

• Check README.md for full documentation
• Run python test_server.py for diagnostics
• Review logs in server.log (if configured)
• Check allowed commands in config.py

---

Created for Windows 11 • Python 3.10+ • MCP Protocol