mcp-python/UVX_USAGE.md

⚡ Using MCP Python Manager with uvx

This guide explains how to use the MCP Python Project Manager server with uv and uvx for faster, simpler execution.

Why uvx?

✅ No virtual environment setup - Run directly without python -m venv
✅ Instant startup - uv's caching makes repeated runs lightning fast
✅ Dependency isolation - Each run uses isolated dependencies
✅ Cross-platform - Works the same on Windows, macOS, and Linux
✅ Automatic updates - uvx fetches the latest version automatically

🚀 Quick Start

Install uv (one-time)

# Via winget (Windows)
winget install astral-sh.uv

# Or via pip
pip install uv

# Verify installation
uv --version
uvx --version

Run the MCP Server

# Basic run (recommended for MCP clients)
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 logging
uvx --from C:/Users/dimir/proects/mcp-python mcp-python-manager --debug

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

Run from Project Directory

If you're already in the project directory:

cd C:\Users\dimir\proects\mcp-python
uvx --from . mcp-python-manager

🔌 Claude Desktop Configuration

Add to %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",
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

Environment Variables Explained

Variable	Purpose	Recommended Value
MCP_PYTHON_WORKSPACE	Root directory for Python projects	C:/Users/dimir/projects
UV_NO_CACHE	Disable uv cache (0 = use cache)	0
UV_LINK_MODE	How uv links packages (copy, symlink, hardlink)	copy (safest on Windows)
PYTHONUNBUFFERED	Disable Python output buffering	1

🔧 Cursor / VS Code Configuration

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

🛠️ Development with uvx

Test Changes Locally

# After editing server.py or tools.py, test immediately:
uvx --from C:/Users/dimir/proects/mcp-python mcp-python-manager --debug

# No need to reinstall - uvx picks up local changes!

Install for Development

# Install with dev dependencies
uv pip install -e ".[dev]" --system

# Run tests
uv run pytest tests/ -v

# Run linting
uv run ruff check .
uv run black --check .

Build and Publish (Optional)

# Build distribution
uv build

# Publish to PyPI (requires token)
uv publish --token $PYPI_TOKEN

🐛 Troubleshooting uvx

"Command not found: uvx"

# Install uv
winget install astral-sh.uv
# or
pip install uv

# Ensure it's in PATH
where uvx

Permission errors on Windows

# Use copy link mode (safer than symlinks on Windows)
set UV_LINK_MODE=copy
uvx --from . mcp-python-manager

# Or run as Administrator if needed

Cache issues

# Clear uv cache
uv cache clean

# Disable cache for one run
uvx --no-cache --from . mcp-python-manager

Slow first run

The first uvx run downloads dependencies. Subsequent runs are instant due to caching.

# Pre-warm cache (optional)
uvx --from . mcp-python-manager --help

Debug uvx behavior

# Enable uv debug output
set UV_VERBOSE=1
uvx --from . mcp-python-manager --debug

# See what uvx is doing
set RUST_LOG=uv=debug
uvx --from . mcp-python-manager

📊 Performance Comparison

Method	First Run	Subsequent Runs	Setup Time
python server.py + venv	~30s	~1s	~2 min (venv + pip)
uvx --from .	~15s	~0.5s	0s
pip install -e . + run	~45s	~1s	~3 min

🔄 Updating the Server

With uvx, updates are automatic:

# Just run again - uvx fetches latest code
uvx --from C:/Users/dimir/proects/mcp-python mcp-python-manager

# Or force refresh
uv cache clean mcp-python-manager
uvx --from C:/Users/dimir/proects/mcp-python mcp-python-manager

📁 Project Structure for uvx

mcp-python/
├── pyproject.toml    # [project.scripts] defines entry points
├── server.py         # Contains run_server() entry point
├── .uvrc             # uv-specific configuration (optional)
└── ...

Key pyproject.toml Settings

[project.scripts]
# This creates the 'mcp-python-manager' command
mcp-python-manager = "server:run_server"

[tool.uv]
# uv-specific optimizations
dev-dependencies = ["dev"]

🎯 Best Practices

1. Use --from . when in project directory - Faster than full path
2. Set UV_LINK_MODE=copy on Windows - Avoids symlink permission issues
3. Keep MCP_PYTHON_WORKSPACE in env - Consistent project access
4. Use --debug during development - See detailed logs
5. Cache warmup - Run --help once to pre-download dependencies

🔄 Switching Back to Python

If you need to use traditional Python:

# Traditional setup
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
python server.py

Both methods work - choose what fits your workflow!

---

uv Documentation: https://docs.astral.sh/uv/
MCP Specification: https://modelcontextprotocol.io