uv manager for AI agents and MCP servers: the only Python manager you need

AI agents write Python code for you. MCP servers extend what your agents can do. Both need Python packages, virtual environments, and sometimes specific Python versions. uv handles all of that in one tool.

If you followed the macOS AI agent setup guide, uv is already installed.

Why uv matters

When an AI agent installs a Python package, it has two options:

• pip install puts packages into your global system. Different projects start conflicting. Things break.
• uv add installs packages into an isolated environment per project. Nothing leaks, nothing conflicts.

The same applies to MCP servers. Each server should run in its own environment. uv makes this the default behavior.

New projects

Starting a new Python project takes three commands:

mkdir my-project && cd my-project
uv init                 # creates the project with a pyproject.toml file
uv add requests         # creates a virtual environment and installs the package
uv run main.py          # runs the script inside the virtual environment

uv init creates a pyproject.toml - the modern replacement for requirements.txt. When you uv add a package, it creates an isolated virtual environment automatically. No manual activation. No source .venv/bin/activate. Just uv run and everything works.

Existing projects

For a project with requirements.txt:

cd existing-project
uv venv                                # creates a virtual environment
uv pip install -r requirements.txt     # installs dependencies

For a project with pyproject.toml (the modern way):

cd existing-project
uv sync                                # installs dependencies

Python versions

Sometimes a project requires a specific Python version. No need to download anything from a website:

uv python install 3.12         # download and install Python 3.12
uv python pin 3.12             # lock this version for the current project

The pin command creates a .python-version file. All uv commands in this folder will use that version automatically.

Running tools without installing them

Need to lint or format code without adding tools to your project? uvx runs them on the fly:

uvx ruff check . # lint the code
uvx ruff format . # format the code
uvx pytest # run tests

The tool runs once and leaves no trace.

Running MCP servers

Many MCP servers are Python packages. Run them directly with uvx:

uvx mcp-server-sqlite --db-path ./my-database.db
uvx mcp-server-filesystem /path/to/allowed/dir1

When configuring MCP servers in your agent's config (like claude_desktop_config.json), point directly to uvx:

{
  "mcpServers": {
    "sqlite": {
      "command": "uvx",
      "args": ["mcp-server-sqlite", "--db-path", "./data.db"]
    }
  }
}

Each server runs in an isolated environment. No global installs, no conflicts between servers.

Basic AGENTS.md for Python project

Add this to your project's and rename to AGENTS.md:

Command reference