MCP Python Venv Server

A comprehensive Python virtual environment inspector for Cursor IDE using the Model Context Protocol (MCP).

Features

🔍 Virtual Environment Detection - Automatically find and analyze Python virtual environments
📦 Package Management - List, check, and compare installed packages
📋 Requirements Analysis - Compare installed packages with requirements files
🐍 Python Version Detection - Get Python version information from virtual environments
🔧 Multi-Format Support - Support for requirements.txt, pyproject.toml, Pipfile, and more
⚡ UV Support - Full support for uv-managed environments
🎯 Flexible Configuration - Choose between pip and uv via environment variables

Supported Package Managers

✅ Fully Supported:

pip - Python package manager
uv - Fast Python package manager (recommended)
pipenv - Python dependency management

❌ Not Supported:

PDM - Python Dependency Manager (not yet implemented)
Poetry - Limited support (detection only, no package operations)

Installation

npm install -g @pceuropa/mcp-server-python-venv

Usage

For better control, specify the package manager explicitly:

{
  "mcpServers": {
    "python-venv": {
      "command": "npx",
      "args": ["@pceuropa/mcp-server-python-venv"],
      "transport": "stdio",
      "env": {
        "PYTHON_PATH": "${workspaceFolder}/.venv/bin/python",
        "VIRTUAL_ENV": "${workspaceFolder}/.venv",
        "UV_PATH": "/path/to/uv"
      }
    }
  }
}

Alternative for pip-managed projects:

{
  "mcpServers": {
    "python-venv": {
      "command": "npx",
      "args": ["@pceuropa/mcp-server-python-venv"],
      "transport": "stdio",
      "env": {
        "PYTHON_PATH": "${workspaceFolder}/.venv/bin/python",
        "VIRTUAL_ENV": "${workspaceFolder}/.venv",
        "PIP_PATH": "${workspaceFolder}/.venv/bin/pip"
      }
    }
  }
}

Available Tools

`ping`

Test server connectivity.

`find_venv`

Find virtual environment in the current project.

Input: projectPath (optional) - Project path to search
Output: Virtual environment information

`get_python_version`

Get Python version from the virtual environment.

Output: Python version and path

`list_packages`

List all installed packages in the virtual environment.

Input: sortBy (optional) - Sort by "name" or "version"
Output: List of installed packages

`check_package`

Check if a specific package is installed and matches version requirements.

Input:
- packageName (required) - Name of the package
- version (optional) - Version requirement (e.g., ">=1.0.0", "==2.1.0")
Output: Package installation status and version info

`compare_requirements`

Compare installed packages with requirements files.

Input: file (optional) - Specific requirements file to check
Output: Missing, extra, and mismatched packages with install command

`check_outdated`

Check for outdated packages in the virtual environment.

Output: List of outdated packages with upgrade commands

`suggest_venv_setup`

Get suggestions for setting up a virtual environment.

Output: Setup commands and tool recommendations

`get_venv_summary`

Get a comprehensive summary of the virtual environment.

Output: Python version, package count, size, requirements status, and outdated count

`get_dependency_tree`

Get dependency tree visualization for packages.

Input:
- package (optional) - Specific package to analyze
- depth (optional) - Maximum depth of dependency tree (default: 3)
Output: Dependency tree with circular dependencies and unused packages

`detect_environment_manager`

Detect which Python environment manager is being used.

Input: projectPath (optional) - Project path to analyze
Output: Detected manager (venv, poetry, pipenv, conda, uv) with config files

`get_poetry_info`

Get Poetry project information and dependencies.

Input: projectPath (optional) - Project path
Output: Poetry project details, dependencies, and environment info
Note: Limited support - detection only, package operations may not work

`get_pipenv_info`

Get Pipenv project information and dependencies.

Input: projectPath (optional) - Project path
Output: Pipenv project details, dependencies, and environment info

`get_conda_info`

Get Conda environment information and packages.

Input: projectPath (optional) - Project path
Output: Conda environment details, packages, and configuration
Note: Basic support - may have limited functionality

`check_security`

Check for security vulnerabilities in installed packages.

Output: List of vulnerabilities with severity and fix recommendations

`check_licenses`

Check licenses of installed packages and identify potential issues.

Output: License information with warnings for problematic licenses

`search_package`

Search for packages on PyPI.

Input:
- query (required) - Search query
- limit (optional) - Maximum results (default: 10)
Output: Search results with package information

`export_environment`

Export current environment to various formats.

Input: format (required) - Export format: "requirements", "pyproject", or "conda"
Output: Formatted environment specification

Environment Variables

The server supports the following environment variables for configuration:

Variable	Description	Priority
`UV_PATH`	Path to uv executable (forces uv usage)	Highest
`PIP_PATH`	Path to pip executable (forces pip usage)	High
`PYTHON_PATH`	Path to Python executable	Medium
`VIRTUAL_ENV`	Path to virtual environment	Medium

Priority Order:

UV_PATH - If set, uses uv pip for all operations
PIP_PATH - If set, uses specified pip executable
Auto-detection - Detects package manager from project files

Limitations

Not Supported Package Managers

PDM (Python Dependency Manager) - Not yet implemented
Poetry - Limited support (detection only, no package operations)

Known Issues

Poetry environments - Can detect but cannot list packages
PDM environments - Not detected or supported
Mixed environments - May not work correctly if using multiple package managers

Troubleshooting

Server Not Finding Virtual Environment

Check environment variables:
```
echo $VIRTUAL_ENV
echo $PYTHON_PATH
```

Use explicit paths in MCP configuration:

{
  "env": {
    "VIRTUAL_ENV": "/absolute/path/to/your/venv",
    "PYTHON_PATH": "/absolute/path/to/your/venv/bin/python"
  }
}

Restart Cursor IDE after configuration changes

Empty Package List

For UV projects: Ensure UV_PATH is set
For pip projects: Ensure PIP_PATH is set

Check package manager detection:

npx @pceuropa/mcp-server-python-venv
# Then call detect_environment_manager tool

Development

Testing the Installation

Test with npx

# Test the server directly
npx @pceuropa/mcp-server-python-venv

# Test with a specific command
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | npx @pceuropa/mcp-server-python-venv

Test in Cursor

Add the configuration to your .cursor/settings.json
Restart Cursor IDE
Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
Type "MCP" and select "MCP: Show Servers"
Verify that "python-venv" server is connected

Prerequisites

Node.js 18+
Python 3.8+
npm or yarn

Setup

git clone https://github.com/pceuropa/mcp-server-python-venv.git
cd mcp-server-python-venv
npm install

Build

npm run build

Development Mode

npm run dev

Testing

npm test

Linting

npm run lint
npm run format

Supported Virtual Environment Types

venv - Standard Python venv
virtualenv - Virtualenv package
uv - UV package manager (recommended)
pipenv - Pipenv environments
conda - Conda environments
poetry - Poetry environments (detection only)

Supported Requirements Formats

requirements.txt
requirements-dev.txt
requirements-test.txt
pyproject.toml (project dependencies)
pyproject.toml (poetry dependencies - limited support)
Pipfile
setup.py (basic support)

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our GitHub repository.

Support

NPM: Package
Discussions: GitHub Discussions
Email: info@pceuropa.net

Changelog

See CHANGELOG.md for version history and updates.

Name		Name	Last commit message	Last commit date
Latest commit History 18 Commits
docs		docs
examples		examples
src		src
tests/unit		tests/unit
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.prettierrc		.prettierrc
.python-version		.python-version
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
PUBLICATION_READY.md		PUBLICATION_READY.md
PUBLISH.md		PUBLISH.md
QUICK_START.md		QUICK_START.md
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
pyproject.toml		pyproject.toml
tsconfig.json		tsconfig.json
uv.lock		uv.lock
vitest.config.ts		vitest.config.ts

License

pceuropa/mcp-server-python-venv

Folders and files

Latest commit

History

Repository files navigation

MCP Python Venv Server

Features

Supported Package Managers

Installation

Usage

Available Tools

ping

find_venv

get_python_version

list_packages

check_package

compare_requirements

check_outdated

suggest_venv_setup

get_venv_summary

get_dependency_tree

detect_environment_manager

get_poetry_info

get_pipenv_info

get_conda_info

check_security

check_licenses

search_package

export_environment

Environment Variables

Limitations

Not Supported Package Managers

Known Issues

Troubleshooting

Server Not Finding Virtual Environment

Empty Package List

Development

Testing the Installation

Test with npx

Test in Cursor

Prerequisites

Setup

Build

Development Mode

Testing

Linting

Supported Virtual Environment Types

Supported Requirements Formats

License

Contributing

Support

Changelog

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

`ping`

`find_venv`

`get_python_version`

`list_packages`

`check_package`

`compare_requirements`

`check_outdated`

`suggest_venv_setup`

`get_venv_summary`

`get_dependency_tree`

`detect_environment_manager`

`get_poetry_info`

`get_pipenv_info`

`get_conda_info`

`check_security`

`check_licenses`

`search_package`

`export_environment`

Packages