mcp-pypi 3.0.0

🐍 AI-powered Python package intelligence - search, analyze, and understand PyPI packages through MCP

🐍 MCP-PyPI

A security-focused Model Context Protocol (MCP) server that helps AI agents write safer Python code. Search packages, scan for vulnerabilities, audit dependencies, and ensure security across your entire Python project.

✨ What is MCP-PyPI?

MCP-PyPI is a security-focused Model Context Protocol server that empowers AI assistants to write safer Python code. Beyond basic package information, it provides comprehensive vulnerability scanning, dependency auditing, and proactive security recommendations to ensure AI-generated code uses secure, up-to-date dependencies.

🛡️ Security First: Every tool is designed to encourage security best practices, from checking vulnerabilities before suggesting packages to scanning entire project dependency trees for hidden risks.

🎯 Key Features

• 🛡️ Comprehensive Security Scanning - Check vulnerabilities using OSV database across packages, dependencies, and entire projects
• 🔍 Security-Aware Package Search - Find safe packages from 500,000+ options with vulnerability status
• 📋 Project-Wide Security Audits - Scan requirements.txt, pyproject.toml, and installed environments
• 🔗 Deep Dependency Analysis - Detect vulnerabilities in transitive dependencies others might miss
• 🚨 Proactive Security Alerts - Get warnings before adding vulnerable packages to projects
• 📊 Risk Assessment & Scoring - Security scores, fix time estimates, and prioritized remediation plans
• ⚡ Smart Caching - Fast vulnerability checks with configurable TTL for different data types
• 🚀 Version Management - Track releases, compare versions, identify security updates
• 🤖 LLM-Safe Tool Annotations - FastMCP 2.14.4 powered with tool annotations for safe AI agent interactions
• 🧩 Modular Architecture - Clean separation of tools, operations, and CLI for maintainability

🤔 Why Security Matters

When AI assistants suggest Python packages, they might unknowingly recommend packages with known vulnerabilities. MCP-PyPI ensures that:

• Before Installation: AI checks for vulnerabilities before suggesting any package
• During Development: Continuous scanning catches new vulnerabilities in existing dependencies
• Before Deployment: Comprehensive audits ensure production code is secure
• Transitive Safety: Hidden vulnerabilities in dependencies-of-dependencies are detected

🚀 Quick Start

System Requirements

• Python 3.10 or higher
• pip package manager
• Virtual environment (recommended)
• fastmcp>=2.14.4 (installed automatically)

Installation

# Basic installation
pip install mcp-pypi

# With HTTP transport support
pip install "mcp-pypi[http]"

# With all features
pip install "mcp-pypi[all]"

Running the Server

# Start with default stdio transport (for Claude Desktop)
mcp-pypi serve

# Alternative stdio command (for compatibility)
mcp-pypi stdio

# Start with HTTP transport
mcp-pypi serve --transport http

# With custom cache directory
mcp-pypi serve --cache-dir ~/.pypi-cache

🤖 Using with Claude Desktop

Add to your Claude Desktop configuration (claude.json):

{
  "servers": {
    "pypi": {
      "command": "mcp-pypi",
      "args": ["serve"],
      "description": "Access Python package information from PyPI"
    }
  }
}

// Alternative using stdio command (equivalent to above)
{
  "servers": {
    "pypi": {
      "command": "mcp-pypi",
      "args": ["stdio"],
      "description": "Access Python package information from PyPI"
    }
  }
}

🖥️ Using with Claude Code (Terminal)

Add the MCP server to Claude Code:

# Add the server (using serve command)
claude mcp add mcp-pypi -- mcp-pypi serve

# Alternative using stdio command
claude mcp add mcp-pypi -- mcp-pypi stdio

# The server will be available in your next Claude Code session

🖱️ Using with Cursor IDE

Cursor IDE supports MCP servers through configuration files. You can configure mcp-pypi either globally (available in all projects) or per-project.

Quick Setup via Settings UI

1. Open Cursor Settings (Cmd+, on Mac, Ctrl+, on Windows/Linux)
2. Navigate to Features > Model Context Protocol
3. Click Add New MCP Server
4. Enter the configuration shown below

Configuration File Setup

Global Configuration (available in all projects):

Platform	Location
macOS/Linux	~/.cursor/mcp.json
Windows	C:\Users\YourUsername\.cursor\mcp.json

Project Configuration (project-specific): Create .cursor/mcp.json in your project root.

Configuration Example

Add mcp-pypi to your mcp.json file:

{
  "mcpServers": {
    "mcp-pypi": {
      "command": "mcp-pypi",
      "args": ["serve"]
    }
  }
}

With custom options:

{
  "mcpServers": {
    "mcp-pypi": {
      "command": "mcp-pypi",
      "args": ["serve", "--log-level", "DEBUG"],
      "env": {
        "PYPI_CACHE_DIR": "/path/to/cache"
      }
    }
  }
}

Verification

1. Restart Cursor completely after adding the configuration
2. Open any project and switch to Agent Mode (not Ask Mode)
3. The MCP tools should appear in the tools list
4. Test by asking: "Search for web scraping packages on PyPI"

Troubleshooting Cursor

Issue	Solution
Tools not appearing	Ensure Cursor is in Agent Mode, not Ask Mode
Server not starting	Check mcp-pypi is installed and in PATH
Configuration errors	Open Output panel (Cmd+Shift+U) and select "MCP Logs"
Server crashes	Toggle server off/on in Settings without removing config

🛠️ Available Tools

Package Discovery

• search_packages - 🔍 Search PyPI to discover Python packages
• get_package_info - 📦 Get comprehensive package details
• check_package_exists - ✅ Verify if a package exists on PyPI

Version Management

• get_latest_version - 🚀 Check the latest available version
• get_package_releases - 📅 Get detailed release information for a package
• list_package_versions - 📚 List all available versions
• compare_versions - 🔄 Compare two package versions

Dependency Analysis

• get_dependencies - 🔗 Analyze package dependencies
• get_dependency_tree - 🌳 Visualize complete dependency tree
• check_vulnerabilities - 🛡️ Scan for security vulnerabilities using OSV database
• scan_dependency_vulnerabilities - 🛡️🔍 Deep scan entire dependency tree for vulnerabilities

Project Management

• check_requirements_txt - 📋🛡️ Security audit requirements.txt files
• check_pyproject_toml - 🎯🛡️ Security audit pyproject.toml dependencies
• scan_installed_packages - 🛡️💻 Scan virtual/system environments for vulnerabilities
• security_audit_project - 🛡️🔍🚨 Comprehensive project-wide security audit
• quick_security_check - 🚦 Quick pass/fail security check for CI/CD
• get_security_report - 🛡️📊 Beautiful, color-coded security report

Statistics & Info

• get_package_stats - 📊 Get download statistics
• get_package_metadata - 📋 Access complete metadata
• get_package_documentation - 📖 Find documentation links
• get_package_changelog - 📝 Get changelog information from GitHub releases

💡 Example Usage

Once configured, you can ask Claude:

• "Search for web scraping packages on PyPI"
• "What's the latest version of Django?"
• "Check if my requirements.txt has any outdated packages"
• "Show me the dependencies for FastAPI"
• "Find popular data visualization libraries"
• "Compare pandas version 2.0.0 with 2.1.0"

🔧 Advanced Configuration

Environment Variables

# Custom cache directory
export PYPI_CACHE_DIR=/path/to/cache

# Cache TTL (seconds)
export PYPI_CACHE_TTL=3600

# Vulnerability cache TTL (seconds) - default 1 hour
export PYPI_VULNERABILITY_CACHE_TTL=3600

# Custom user agent
export PYPI_USER_AGENT="MyApp/1.0"

Programmatic Usage

from mcp_pypi.server import PyPIMCPServer
from mcp_pypi.core.models import PyPIClientConfig

# Custom configuration
config = PyPIClientConfig(
    cache_dir="/tmp/pypi-cache",
    cache_ttl=7200,
    cache_strategy="hybrid"
)

# Create and run server
server = PyPIMCPServer(config=config)
server.run(transport="http", host="0.0.0.0", port=8080)

📊 Performance

• Intelligent Caching: Hybrid memory/disk caching with LRU/LFU/FIFO strategies
• Concurrent Requests: Async architecture for parallel operations
• Minimal Overhead: Direct PyPI API integration
• Configurable TTL: Control cache duration based on your needs

🛡️ Security & Caching

Vulnerability Data Caching

Vulnerability checks are cached to improve performance and reduce API load:

• Default TTL: 1 hour (3600 seconds)
• Configurable: Use PYPI_VULNERABILITY_CACHE_TTL environment variable
• Cache Key: Based on package name + version
• OSV API: Queries are cached to avoid repeated lookups

Why Caching Matters

1. Performance: Vulnerability checks can be slow, caching makes subsequent checks instant
2. Rate Limiting: Prevents hitting OSV API rate limits during large scans
3. Consistency: Ensures consistent results during a security audit
4. Offline Support: Cached results available even if OSV API is unreachable

Cache Management

# Clear all caches
mcp-pypi cache clear

# View cache statistics
mcp-pypi cache stats

# Set shorter TTL for development (5 minutes)
export PYPI_VULNERABILITY_CACHE_TTL=300

🖥️ CLI Usage

MCP-PyPI includes a full-featured command-line interface for direct package operations:

Help and Documentation

# Show version
mcp-pypi --version

# Display README documentation
mcp-pypi --readme

# Show changelog
mcp-pypi --changelog

# Get connection examples
mcp-pypi serve --help-connecting
mcp-pypi stdio --help-connecting

Package Information

# Search for packages
mcp-pypi search "web scraping"

# Get package info
mcp-pypi package info requests

# Check latest version
mcp-pypi package version django

# List all versions
mcp-pypi package releases numpy

# Get dependencies
mcp-pypi package dependencies flask

# Compare versions
mcp-pypi package compare pandas 2.0.0 2.1.0

Security Checks

# Check requirements file
mcp-pypi check-requirements /path/to/requirements.txt

# View package statistics
mcp-pypi stats downloads requests

Cache Management

# Clear cache
mcp-pypi cache clear

# View cache statistics
mcp-pypi cache stats

❓ Troubleshooting

Common Issues

Connection Issues with stdio

• Ensure you're using the absolute path to mcp-pypi in your configuration
• Try using mcp-pypi stdio instead of mcp-pypi serve for better compatibility
• Check logs with --log-level DEBUG for detailed error messages

Token Limit Errors

• Some operations like changelog retrieval are automatically limited to prevent token overflow
• Use more specific queries when searching for packages
• Check individual packages rather than bulk operations

Cache Issues

• Clear cache with mcp-pypi cache clear if you see stale data
• Adjust cache TTL with environment variables for your use case
• Default cache location is ~/.cache/mcp-pypi/

Import Errors

• Ensure you have Python 3.10+ installed
• Install with pip install "mcp-pypi[all]" for all dependencies
• Use a virtual environment to avoid conflicts

🤝 Contributing

Contributions are welcome! Please check out our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/kimasplund/mcp-pypi.git
cd mcp-pypi

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# Run with debug logging
mcp-pypi serve --log-level DEBUG

📄 License

This project is dual-licensed:

• Open Source: MIT License for personal, educational, and non-profit use - see LICENSE
• Commercial: Commercial License required for business use - see LICENSE-COMMERCIAL

Quick License Guide:

• ✅ Free to use: Personal projects, education, non-profits, open source
• 💰 Commercial license required: For-profit companies, commercial products, consulting
• 📧 Contact: [e-mail] for commercial licensing

🙏 Acknowledgments

• Built on the Model Context Protocol
• Powered by the Python Package Index
• Security scanning via OSV (Open Source Vulnerabilities) database by Google
• Enhanced with FastMCP 2.14.4 - tool annotations for LLM safety

📞 Support

• 🌐 Website: asplund.kim
• 📧 Email: [e-mail]
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

---

Made with ❤️ for the Python and AI communities