DEV Community

Saadman Rafat
Saadman Rafat

Posted on

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

#devtools #ai #uv #gemini

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. "It works on my machine."

We often use AI assistants (like Claude, Gemini, or ChatGPT) to debug these issues. We paste an error log, the AI suggests a command, we copy-paste it into the terminal, fail, paste the new error... repeat.

But what if your AI could just fix the environment for you?

Enter uv-mcp—an open-source tool that bridges the gap between the blazing fast uv package manager and your AI assistant using the Model Context Protocol (MCP).

What is uv-mcp?

uv-mcp is an MCP 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 just 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.

Here are the superpowers it unlocks:

1. The "Doctor" Check

The diagnose_environment tool performs a comprehensive health check on your project. It looks at:

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

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 is magic. It 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.

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? You don't need to remember the flags for dev dependencies or optional groups.

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 (like the Gemini CLI or Claude Desktop).

Option 1: Gemini CLI (Easiest)

If you use the Gemini CLI, installation is one command:

gemini extensions install https://github.com/saadmanrafat/uv-mcp
Enter fullscreen mode Exit fullscreen mode

Option 2: Claude Desktop

To use this with Claude Desktop, you just need to configure it in your claude_desktop_config.json:

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

(Note: You'll need to clone the repo locally for this method).

Example Workflow

Here is what a conversation looks like when you have uv-mcp installed.

User: "I want to start a new data science project in this folder."

AI: "I'll set that up for you."

  1. Calls diagnose_environment -> "Empty folder detected."
  2. Calls repair_environment -> Creates pyproject.toml and .venv.
  3. Calls add_dependency("pandas")
  4. 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 here:
👉 github.com/saadmanrafat/uv-mcp

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

Top comments (0)