Give Your AI Superpowers: Managing Python Environments with uv-mcp

Source: Dev.to

If you’ve been coding in Python for more than a week, you know the struggle: virtual environments, requirements.txt vs pyproject.toml, dependency conflicts, and the classic “It works on my machine.”

We often turn to AI assistants (Claude, Gemini, ChatGPT) to debug these issues: paste an error log, get a suggested command, copy‑paste into the terminal, fail, repeat.

What if your AI could just fix the environment for you?

What is uv-mcp?

uv-mcp is an MCP (Model Context Protocol) server that wraps the functionality of uv—Astral’s ultra‑fast Python package manager. By running this server, you give your AI agent direct access to tools that can check, diagnose, and repair your Python development environment. Instead of merely telling you what to type, the AI can execute the necessary uv commands to get your project running.

Why You Need This

We are moving from “Chatbots” to “Agents.” A chatbot gives advice; an agent takes action. uv-mcp turns your AI into a Python DevOps agent.

1. The “Doctor” Check

The diagnose_environment tool performs a comprehensive health check on your project, examining:

• Project structure (pyproject.toml, requirements.txt)
• Virtual environment status
• Dependency health and version conflicts
• Lockfile presence

Example interaction

• You: “Why isn’t my project running?”
• AI (using tool): “I see you’re missing a virtual environment and your pyproject.toml is out of sync. Shall I fix it?”

2. The “Auto‑Fix” Button

The repair_environment tool can automatically:

• Create a virtual environment if one is missing
• Initialize a pyproject.toml for new projects
• Sync dependencies from your lockfile
• Update outdated packages

Example interaction

• You: “Yes, please fix it.”
• AI (using tool): Executes repair sequence… “Done! I’ve created the venv and synced your dependencies. You’re ready to code.”

3. Dependency Management

Need to add a package? No more remembering flags for dev dependencies or optional groups.

Example interaction

• You: “Install pytest and black as dev dependencies.”
• AI (using tool): Calls add_dependency(package="pytest", dev=True) …

Getting Started

Because this uses the standard Model Context Protocol, it works with any MCP‑compliant client (e.g., the Gemini CLI or Claude Desktop).

Option 1: Gemini CLI (Easiest)

If you use the Gemini CLI, install the extension with a single command:

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

Option 2: Claude Desktop

Configure Claude Desktop in your claude_desktop_config.json:

{
  "mcpServers": {
    "uv-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/cloned/uv-mcp",
        "run",
        "uv-mcp"
      ]
    }
  }
}

(Note: You’ll need to clone the repository locally for this method.)

Example Workflow

A typical conversation with uv-mcp installed might look like this:

• User: “I want to start a new data‑science project in this folder.”
• AI: “I’ll set that up for you.”
  • Calls diagnose_environment → “Empty folder detected.”
  • Calls repair_environment → Creates pyproject.toml and .venv.
  • Calls add_dependency("pandas").
  • Calls add_dependency("jupyter", dev=True).
• AI: “Project initialized! I’ve set up the environment and installed Pandas and Jupyter.”

Try It Out

The era of copy‑pasting terminal commands is ending. Let your AI handle the environment so you can focus on the code.

Check out the repository: github.com/saadmanrafat/uv-mcp

Give it a star if you find it useful, and happy coding!