UV-MCP

The Stop Shop for Python Environment Management

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 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 to install and configure UV-MCP for your preferred client.
Explore the Usage Guide for real-world workflows and command patterns.
Browse the Tool Reference for complete API documentation.

Built with care by Saadman Rafat.