Overview

astral uv mcp (commonly known as uv-mcp) is an open-source Model Context Protocol (MCP) server that bridges Astral's uv—the extremely fast Rust-based Python package and project manager—with AI agents and tools like Claude Desktop, Claude Code, and Gemini CLI.

Instead of AI assistants merely suggesting uv commands, uv-mcp allows them to directly inspect, diagnose, and fix Python project environments, making AI a proactive DevOps partner for Python development.

Features

Environment Diagnostics: Automatically analyzes project structure, virtual environments, dependency conflicts, lockfiles (uv.lock), and pyproject.toml.
Self-Healing Repairs: Creates virtual environments, initializes projects, syncs dependencies, and resolves issues with a single tool call.
Dependency Management: Add, remove, or update packages (including dev dependencies) via natural language—no need to remember flags or commands.
Native uv Integration: Fully respects uv workflows, PEP 668 externally-managed environments, and ensures reproducible setups with uv.lock.
MCP Compatibility: Works seamlessly with MCP clients including Claude, Gemini CLI extensions, and other AI agent platforms.
Scoped & Safe: Operations are project-scoped with no global pollution; ideal for containers, CI/CD, and managed environments.
Auditable & Deterministic: Clear logs and consistent behavior across machines for reliable automation.

Use Cases

AI-Powered Python Setup: Tell your agent "Set up a new data science project with pandas and Jupyter"—it handles uv init, venv creation, and dependency installation.
Environment Troubleshooting: AI diagnoses "why my project isn't running" and repairs it automatically.
Dependency Resolution: Resolve conflicts or update lockfiles without manual intervention.
Multi-Agent Workflows: Integrate into larger MCP/AI agent orchestrations for full-stack Python development automation.
CI/CD & Reproducible Builds: Ensure consistent environments in automated pipelines.

Installation & Quick Start

For Gemini CLI (recommended)

gemini extensions install https://github.com/saadmanrafat/uv-mcp

For Claude Desktop / Code

Clone the repo and add to your MCP configuration (details in the documentation).

Requires uv (Astral's package manager) to be installed. Full guides available in the repository.

Why uv-mcp?

uv is already 10-100x faster than traditional tools like pip/Poetry. uv-mcp supercharges it by giving AI agents direct, safe access to its power—turning "it works on my machine" into reliable, agent-driven reproducibility.

astral uv mcp