# astral uv mcp

uv-mcp is an MCP server that wraps Astral's ultra-fast uv Python package manager, enabling AI agents to diagnose, repair, and manage Python environments through natural language.

Canonical URL: https://a2a-mcp.org/entry/astral-uv-mcp

Language: en

Category: MCP Servers

Updated: 2026-04-06

## Overview

**astral uv mcp** (commonly known as **uv-mcp**) is an open-source **Model Context Protocol (MCP) server** that bridges [Astral's uv](https://docs.astral.sh/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)
```bash
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](https://saadman.dev/uv-mcp/)).

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.

## Links

- GitHub: [saadmanrafat/uv-mcp](https://github.com/saadmanrafat/uv-mcp)
- Documentation: [saadman.dev/uv-mcp](https://saadman.dev/uv-mcp/)
- uv Official Docs: [docs.astral.sh/uv](https://docs.astral.sh/uv/)

Built for the modern AI-native Python ecosystem.

## Tags

- mcp
- uv
- python
- package-manager
- ai-agent
- environment-management
- astral
- devops
- claude
- gemini

## Sources

- [Project website](https://github.com/saadmanrafat/uv-mcp)