---
title: "UV-MCP"
description: "The Stop Shop MCP server for uv. 45 typed tools covering 100% of the uv CLI, built by Saadman Rafat (saadman.dev, x.com/saadmanrafat_)."
template: splash
hero:
  tagline: "The Stop Shop for Python Environment Management"
  actions:
    - text: Get Started
      link: /uv-mcp/guides/introduction/
      icon: right-arrow
      variant: primary
    - text: View on GitHub
      link: https://github.com/saadmanrafat/uv-mcp
      icon: external
      variant: secondary
---

## What is UV-MCP?

UV-MCP is a **Model Context Protocol (MCP)** server that maps natural language to typed `uv` commands. It gives AI assistants — Claude Code, OpenCode, Codex, Gemini CLI, and any MCP client — the ability to manage Python environments, dependencies, and project lifecycles without memorizing 45 different CLI flags.

Instead of typing, you say:

> *"Create a virtual environment with seed packages, install requests, and run my script."*

UV-MCP handles the rest.

## Works With

| Client | Config file | Setup |
|---|---|---|
| **Claude Code** | `.mcp.json` | `claude mcp add uv-mcp -- uv run uv-mcp` |
| **OpenCode** | `opencode.json` | `opencode.json` ships in the repo — open and it's active |
| **Codex CLI** | `.codex/config.toml` | `codex mcp add uv-mcp -- uv run uv-mcp` |
| **Gemini CLI** | `gemini-extension.json` | `gemini extensions install https://github.com/saadmanrafat/uv-mcp` |

See the [Installation guide](/uv-mcp/guides/installation/) for the complete config for each client.

## Key Features

- **45 typed tools** — Every `uv` command is exposed as a structured, type-safe MCP tool with Pydantic models. From `uv add` to `uv publish`, nothing is left behind.
- **Self-healing diagnostics** — Detects `ModuleNotFoundError`, suggests `uv add` fixes, and auto-syncs environments. Broken projects repair themselves.
- **Workspace introspection** — Parses `[tool.uv.workspace]` from `pyproject.toml` and emits topological dependency graphs for monorepos.
- **Ephemeral tool runner** — Run any CLI tool via `uv tool run` without permanent installation. Useful for one-off formatters, linters, and utilities.
- **Concurrency safe** — `asyncio.Lock()` serializes mutating commands to prevent `uv.lock` deadlocks during concurrent AI tool calls.
- **ANSI-free output** — Guaranteed clean, parseable streams by injecting `UV_COLOR=never` and `TERM=dumb` on every subprocess.

## Tool Coverage

| Category | Tools |
|---|---|
| Project Lifecycle | `init`, `version`, `format`, `build`, `publish`, `lock` |
| Dependencies | `add`, `remove`, `sync`, `tree`, `list`, `show`, `outdated`, `freeze` |
| Python | `install`, `pin`, `find`, `upgrade`, `uninstall`, `dir` |
| Virtual Env | `create`, `seed`, `relocatable`, `system-site-packages` |
| Ephemeral | `run script`, `uvx proxy`, `temporary --with` |
| Diagnostics | `check`, `repair`, `self-heal`, `workspace manifest` |

## Next Steps

- Read the [Introduction](/uv-mcp/guides/introduction/) to install and configure UV-MCP for your preferred client.
- Explore the [Usage Guide](/uv-mcp/guides/usage/) for real-world workflows and command patterns.
- Browse the [Tool Reference](/uv-mcp/reference/tools/) for complete API documentation.

Built with care by [Saadman Rafat](https://x.com/saadmanrafat_).