venv

This MCP server provides a lightweight way to manage a Python virtual environment (venv) for a given project using the UV-based MCP runtime. It solves the problem of LLMs failing to reliably create or update virtual environments by offering a dedicated server that can resolve dependencies and prepare the venv in a consistent, reusable way. The integration demonstrates how Claude Desktop (Cline) can fetch and run the server via uvx, enabling seamless interaction with your project’s toolchain. The server itself accepts the --uv-path parameter to locate the underlying uv executable, and it relies on the system’s Python tooling to create and manage the virtual environment as requested by clients.

To use it, you deploy the MCP server via uvx with the provided git source, then run the server so that clients (like Claude) can send dependency lists or environment updates. The server is designed to be invoked with a specific project location and dependency specification, and it handles creating or updating the venv accordingly. This makes it easier to reason about environment reproducibility when working with LLM-assisted automation or integrated desktop assistants.

Prerequisites

• Python 3.8+ and pip (for environments where uvx is installed via Python tooling)
• Git
• Access to install or run uvx (the MCP runner)

Step-by-step installation

1. Ensure Python and Git are installed on your system.

• macOS/Linux: install Python 3.8+ from python.org or your package manager; git is typically preinstalled.
• Windows: install Python from python.org and ensure Python and Scripts are on PATH; Git for Windows can be used for cloning if needed.

2. Install uvx (the MCP runner).

• Using pipx (recommended):
  • python3 -m pip install --user pipx
  • python3 -m pipx ensurepath
  • pipx install uvx
• Or using pip directly:
  • python3 -m pip install uvx

3. Run the MCP server from the provided Git source.

• The README example shows how to reference the server via uvx:

  uvx --from git+https://github.com/sparfenyuk/venv-mcp-server.git venv-mcp-server --help

  This will expose the venv-mcp-server tooling through the UV runtime. You can then integrate it with clients like Claude Desktop by using the specified mcpServers entry.

4. Verify installation by requesting help or a dry-run:

• uvx --from git+https://github.com/sparfenyuk/venv-mcp-server.git venv-mcp-server --help
• This should display the server’s usage information and available options.

Optional: configuring a project path

• When invoking runtime clients, you may pass a path to the target project location so the server can manage the venv in the correct place. The exact arguments depend on how the MCP server exposes the venv management features.

Notes:

• The MCP server relies on the uv runtime to execute and manage dependencies. Ensure the uv executable is accessible in your PATH or explicitly provided via --uv-path.
• If you encounter permission issues when creating or updating the venv, check that the running user has read/write access to the target project directory.
• When using the integration in GUI clients (e.g., Claude Desktop), ensure the client is configured to point to the correct server entry (venv-management-for-my-project in this example).
• If you need to customize the venv location, adjust the server invocation to point to a specific project directory; the server should respect the target path for dependency installation.
• For debugging, running with --help will outline available flags and their expected values.