uv-mcp

A Model Context Protocol (MCP) server for interacting with Python installations via uv, the fast Python package installer.

Overview

uv-mcp provides LLMs with direct access to inspect and manage Python environments through the uv package manager. This allows AI assistants to help with Python dependency management, environment inspection, and troubleshooting tasks.

Features

• Environment Inspection: Query installed packages and their versions
• Environment Comparison: Identify differences between virtual environments
• Requirement Management: Parse requirements.txt and pyproject.toml files
• Package Information: Retrieve metadata about PyPI packages
• Virtual Environment Management: Create and inspect virtual environments
• UV Documentation: Browse cached CLI, settings, and resolver documentation
• Documentation Search: Search the cached UV documentation from an MCP client
• Python Management: Discover, install, pin, upgrade, and remove Python versions
• Tool Management: Install, upgrade, list, and uninstall global uv tools
• Security Auditing: Audit project dependencies and installed uv tools for vulnerabilities and adverse package statuses
• Diagnostics: Diagnose, repair, and self-heal project environments

How It Works

uv-mcp implements the Model Context Protocol to expose Python environment data and package management functionality through standardized resources and tools.

Resources

• python:packages://installed - List of all installed packages and versions
• python:packages://outdated - List of installed packages with newer versions available
• python:packages://{package_name}/info - Detailed information about a package
• python:requirements://{file_path*} - Parsed requirements and version conflicts
• uv:docs://{section} - List entries in the cli, settings, or resolver sections
• uv:docs://{section}/{command} - Read documentation entry metadata
• uv:docs://{section}/{command}/{subsection} - Read detailed documentation content

Tools

• run(command: str[]) - Run a command or script
• init() - Create a new project
• add(package_name: str, version: Optional[str]) - Add dependencies to the project
• remove(package_name: str) - Remove dependencies from the project
• sync(dry_run: bool) - Install all declared dependencies, uninstall anything not declared
• lock() - Update the project's lockfile
• check(project_path: Optional[str], fix: bool) - Check project metadata and dependencies
• project_version(project_path: Optional[str]) - Read the project version
• pip(command: str[]) - Run a pip command
• create_virtualenv(path: str, packages: str[]) - Create a virtual environment
• compare_environments(env1: str, env2: str) - Compare packages in two environments
• pip_install(package_name: str, version: Optional[str], venv_path: Optional[str]) - Install a package
• pip_uninstall(package_name: str, venv_path: Optional[str]) - Uninstall a package
• pip_list(venv_path: Optional[str]) - List packages in an optional target environment
• outdated(venv_path: Optional[str]) - List installed packages with newer versions available
• pip_show(packages: str[], venv_path: Optional[str]) - Show installed package metadata
• pip_tree(venv_path: Optional[str]) / pip_check(venv_path: Optional[str]) - Inspect environment dependencies
• update_cache(force: bool) - Refresh the UV documentation cache
• search_documentation(query: str) - Search cached UV documentation
• python_list() / python_install(version) / python_pin(version) - Manage Python installations
• python_find(request) / python_upgrade(version) / python_uninstall(version) - Resolve and update Python versions
• tool_install(package) / tool_upgrade(name) / tool_list() / tool_uninstall(name) - Manage uv tools
• tool_dir(bin: bool) / tool_update_shell() - Inspect and configure the uv tools directory
• python_update_shell() - Configure the uv-managed Python directory on PATH
• workspace_metadata() / workspace_list() / workspace_dir(package?) - Inspect workspaces
• audit(...) / tool_audit(...) - Audit project dependencies or installed uv tools for vulnerabilities
• cache_clean(package) / cache_prune(ci) / cache_dir() / cache_size() - Manage the uv cache
• diagnose_environment(project_path) / repair_environment(project_path) / self_heal(project_path) - Inspect and repair environments
• pip_compile(input_file) / pip_sync(requirements_file) / pip_freeze() - Run pip-compatible workflows
• build(project_path) / publish(project_path) / bump_version(level) - Build and publish projects
• self_version() / self_update(target_version) - Inspect and update uv

Prompts

• summarize_docs(section: Optional[str]) - Generate a prompt for summarizing UV documentation

Usage

To start the server:

uvx uv-mcp

The server checks for .venv or venv in its working directory. To select an explicit virtual environment, use the serve command:

uvx uv-mcp serve /path/to/.venv

Install the bundled Agent Skill into a project for agents that discover skills from .agents/skills:

uvx uv-mcp skill install uv

Use --target /path/to/project to select another project directory, or --force to replace an existing installation.

Configuration can also be provided through environment variables:

• UV_MCP_VENV_PATH - Default virtual environment path
• UV_MCP_LOG_LEVEL - Logging level, default INFO
• UV_MCP_UV_BINARY - Explicit path to the uv executable
• UV_MCP_COMMAND_TIMEOUT - Optional uv command timeout in seconds
• UV_MCP_CACHE_DIR - Documentation cache directory; defaults to the XDG cache directory

uv's optional malware check can be enabled for sync operations with UV_MALWARE_CHECK=1.

Development

This project is built with FastMCP and uv.