# How to use uvx to run Python MCP servers

- Tool: MCP
- Difficulty: Beginner
- Time required: 10-15 min
- Compatibility: Python 3.10+, uv 0.4+, all MCP hosts
- Last updated: March 2026

## TL;DR

uvx is Python's equivalent of npx — it runs Python-based MCP servers without requiring manual pip install or virtual environment setup. Install uv first with curl -LsSf https://astral.sh/uv/install.sh | sh, then configure your MCP host to use uvx as the command. uvx automatically creates isolated environments and resolves dependencies, making Python MCP servers as easy to run as npm-based ones.

## Running Python MCP Servers with uvx

Python MCP servers are typically distributed as PyPI packages and can be run with uvx, the tool runner included with uv. uvx automatically handles dependency resolution, virtual environment creation, and execution in a single command — no pip install or virtualenv setup needed. This tutorial walks you through installing uv, configuring uvx-based MCP servers, and troubleshooting common issues.

## Before you start

- Python 3.10+ installed on your system
- An MCP host like Claude Desktop or Cursor installed
- Terminal access for installing uv
- Basic familiarity with your MCP host's configuration file

## Step-by-step guide

### 1. Install uv on your system

uv is a fast Python package installer and runner developed by Astral (the team behind Ruff). Install it using the official install script. On macOS and Linux, use the curl command below. On Windows, use the PowerShell command. After installation, restart your terminal so the uvx command is available on your PATH.

```
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Verify installation
uvx --version
```

**Expected result:** uvx --version outputs a version number, confirming uv is installed correctly.

### 2. Run a Python MCP server with uvx

uvx runs a Python package as a command-line tool in an isolated environment. It downloads the package, installs its dependencies in a temporary virtual environment, and executes it — all in one step. Test this in your terminal first before adding it to your MCP host config. The command syntax is uvx <package-name> followed by any arguments the server needs.

```
# Run the git MCP server
uvx mcp-server-git --repository /path/to/your/repo

# Run the fetch MCP server
uvx mcp-server-fetch

# Run a specific version
uvx mcp-server-git@0.6.0 --repository /path/to/your/repo
```

**Expected result:** The MCP server starts and outputs protocol messages to stdout (which you will see as JSON-RPC text in the terminal).

### 3. Configure uvx-based servers in your MCP host

Add the uvx-based server to your MCP host configuration. Use uvx as the command and put the package name and any arguments in the args array. Add environment variables in the env block just like you would for npx-based servers. The configuration is identical in structure to npx servers — only the command changes.

```
// claude_desktop_config.json
{
  "mcpServers": {
    "git": {
      "command": "uvx",
      "args": ["mcp-server-git", "--repository", "/Users/yourname/projects/my-repo"]
    },
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    }
  }
}
```

**Expected result:** Your MCP host starts the Python server using uvx and the server's tools appear in the host interface.

### 4. Fix PATH issues for GUI-launched hosts

Just like npx, GUI applications may not find uvx because they do not inherit your shell's PATH. Use the absolute path to uvx in your configuration. Run which uvx in your terminal to find it. On macOS with the official installer, it is typically at ~/.cargo/bin/uvx or ~/.local/bin/uvx. On Homebrew installations, it is /opt/homebrew/bin/uvx.

```
# Find absolute path
which uvx
# Example: /Users/yourname/.local/bin/uvx

# Use absolute path in config
{
  "mcpServers": {
    "git": {
      "command": "/Users/yourname/.local/bin/uvx",
      "args": ["mcp-server-git", "--repository", "/path/to/repo"]
    }
  }
}
```

**Expected result:** The MCP server starts correctly using the absolute path to uvx.

### 5. Add environment variables for Python servers

Many Python MCP servers need API keys or configuration values passed as environment variables. Add them in the env block of your server config, just like npx-based servers. Python servers access these via os.environ. A common pattern is PYTHONUNBUFFERED=1 which forces Python to flush output immediately — important for stdio transport where buffered output can cause communication delays. If you need help configuring complex Python MCP server deployments, the RapidDev engineering team can assist.

```
{
  "mcpServers": {
    "custom-python-server": {
      "command": "uvx",
      "args": ["my-mcp-server"],
      "env": {
        "API_KEY": "your-api-key-here",
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}
```

**Expected result:** The Python MCP server receives the environment variables and uses them for configuration and authentication.

## Complete code example

File: `claude_desktop_config.json`

```json
{
  "mcpServers": {
    "git": {
      "command": "uvx",
      "args": [
        "mcp-server-git",
        "--repository",
        "/Users/yourname/projects/my-repo"
      ]
    },
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    },
    "sqlite": {
      "command": "uvx",
      "args": [
        "mcp-server-sqlite",
        "--db-path",
        "/Users/yourname/data/mydb.sqlite"
      ]
    },
    "custom-api": {
      "command": "uvx",
      "args": ["my-custom-mcp-server"],
      "env": {
        "API_KEY": "sk-your-key",
        "BASE_URL": "https://api.example.com",
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}
```

## Common mistakes

- **Not installing uv before trying to use uvx** — undefined Fix: uvx is part of the uv package. Install uv first using curl -LsSf https://astral.sh/uv/install.sh | sh, then restart your terminal.
- **Using pip install instead of uvx for MCP servers** — undefined Fix: uvx handles everything automatically in an isolated environment. You do not need to create virtualenvs or pip install anything. Just use uvx <package-name>.
- **Not setting PYTHONUNBUFFERED=1 for stdio transport** — undefined Fix: Python buffers stdout by default, which can delay MCP protocol messages. Add PYTHONUNBUFFERED=1 to the env block to force immediate output flushing.
- **Using a relative path to uvx in the MCP config** — undefined Fix: GUI applications may not find uvx via PATH. Use the absolute path from which uvx in your config.

## Best practices

- Always set PYTHONUNBUFFERED=1 in the env block for Python MCP servers using stdio transport
- Use absolute paths to uvx in MCP host configs to avoid PATH resolution issues
- Test the uvx command in your terminal before adding it to the host config
- Pin package versions for production stability: uvx mcp-server-git@0.6.0
- Keep uv updated with uv self update to get the latest package resolution improvements
- Use the env block for API keys — never modify the Python server code to hardcode secrets

## Frequently asked questions

### What is the difference between uvx and npx?

uvx is for Python packages (PyPI), npx is for JavaScript packages (npm). They serve the same purpose — running packages without installing them globally. Use uvx for Python MCP servers and npx for Node.js MCP servers.

### Does uvx install packages permanently?

No, uvx creates temporary isolated environments. Packages are cached locally for faster subsequent runs but are not installed globally or into any project.

### Can I use pip instead of uvx?

Technically yes, but uvx is strongly recommended because it handles environment isolation automatically. Using pip can lead to dependency conflicts with other Python packages on your system.

### How do I update a Python MCP server installed via uvx?

uvx automatically uses the latest version by default. To force a fresh download, run uvx --reinstall <package-name>. To pin a version, use uvx <package-name>@<version>.

### Does uvx work on Windows?

Yes, install uv using the PowerShell command: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex". Unlike npx on Windows, uvx typically works without a cmd wrapper.

### Can I run locally developed Python MCP servers with uvx?

For local development, use uv run instead of uvx. Navigate to your server directory and run uv run python server.py. uvx is designed for published packages, while uv run works with local code.

---

Source: https://www.rapidevelopers.com/mcp-tutorial/how-to-use-uvx-to-run-python-mcp-servers
© RapidDev — https://www.rapidevelopers.com/mcp-tutorial/how-to-use-uvx-to-run-python-mcp-servers