Using uvx to Run MCP Servers in Claude Desktop

Mar 5, 2026

The Problem

I wanted to run an MCP server in Claude Desktop using uvx, but I wasn’t sure how to configure it correctly. I also wondered whether I should use uvx or uv tool install for my use case.

What uvx Actually Is

uvx is just an alias for uv tool run. Both commands run Python tools in isolated, temporary environments without permanently installing them.

# These are equivalent:
uvx ruff check .
uv tool run ruff check .

When I run uvx things-mcp, here’s what happens:

uv creates a temporary virtual environment
Installs the package and its dependencies
Runs the tool
Cleans up (unless cached)

This is perfect for testing different versions and keeping my system clean.

uvx vs uv tool install

I made a comparison table to help decide:

Feature	uvx (uv tool run)	uv tool install
Installation	Ephemeral	Permanent
Environment	Temporary, isolated	Persistent in ~/.local
Startup time	Slower (first run)	Faster
Updates	Automatic	Manual (`uv tool upgrade`)
macOS permissions	New process each time	Single process

Use uvx when:

Testing a new MCP server before committing
Running tools occasionally
Want automatic version updates

Use uv tool install when:

Using the MCP server daily
Need faster startup times
Want to avoid repeated permission prompts on macOS

Basic Configuration

Here’s the simplest way to configure an MCP server with uvx:

{
  "mcpServers": {
    "my-server": {
      "command": "uvx",
      "args": ["package-name"]
    }
  }
}

Specifying Python Version

Some MCP servers require specific Python versions. I found this format works well:

{
  "mcpServers": {
    "my-server": {
      "command": "uvx",
      "args": [
        "--python",
        "3.11",
        "package-name"
      ]
    }
  }
}

Real Examples

things-mcp (macOS)

{
  "mcpServers": {
    "things": {
      "command": "uvx",
      "args": [
        "--python",
        "3.11",
        "things-mcp"
      ]
    }
  }
}

This requires macOS and Things app with Reminders permission.

Git Server

{
  "mcpServers": {
    "git": {
      "command": "uvx",
      "args": [
        "mcp-server-git",
        "--repository",
        "/Users/username/projects/myproject"
      ]
    }
  }
}

With Environment Variables

{
  "mcpServers": {
    "github": {
      "command": "uvx",
      "args": ["mcp-server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Performance Numbers I Measured

First run:  ~2-5 seconds (package download, environment creation)
Cached run: ~0.5-1 second (environment reuse)
Installed:  ~0.1-0.3 seconds (direct execution via uv tool install)

uvx caches downloaded packages, virtual environments, and Python interpreters in ~/.cache/uv/.

To clear the cache:

# Clear all uv cache
uv cache clean

# Clear specific package
uv cache clean things-mcp

Troubleshooting

”uvx: command not found”

Install uv first:

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

# Or with Homebrew
brew install uv

Python Version Not Found

uv can manage Python installations:

uv python install 3.11

# Or use system Python
uvx --python-preference system things-mcp

Package Not Found

Verify the package name or use a Git URL:

uvx --from git+https://github.com/hald/things-mcp things-mcp

Slow Startup

If startup is too slow, switch to permanent installation:

uv tool install things-mcp --python 3.11

Then update your config:

{
  "mcpServers": {
    "things": {
      "command": "things-mcp"
    }
  }
}

Security Tips

I always verify packages before using them. For production, I pin versions:

{
  "mcpServers": {
    "things": {
      "command": "uvx",
      "args": [
        "--python",
        "3.11",
        "things-mcp==1.0.0"
      ]
    }
  }
}

Migration Path

When I want to transition from uvx to permanent installation:

# 1. Install permanently
uv tool install things-mcp --python 3.11

# 2. Update config to use direct command
# 3. Verify
things-mcp --version

# 4. To uninstall later
uv tool uninstall things-mcp

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 uv Tools Documentation
👨‍💻 MCP Specification

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!