🐍 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

Open Cursor Settings (Cmd+, on Mac, Ctrl+, on Windows/Linux)
Navigate to Features > Model Context Protocol
Click Add New MCP Server
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

Restart Cursor completely after adding the configuration
Open any project and switch to Agent Mode (not Ask Mode)
The MCP tools should appear in the tools list
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

Performance: Vulnerability checks can be slow, caching makes subsequent checks instant
Rate Limiting: Prevents hitting OSV API rate limits during large scans
Consistency: Ensures consistent results during a security audit
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: kim.asplund@gmail.com 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: kim.asplund@gmail.com
🐛 Issues: GitHub Issues
💬 Discussions: GitHub Discussions

Made with ❤️ for the Python and AI communities

Name		Name	Last commit message	Last commit date
.github		.github
docs		docs
examples		examples
mcp_pypi		mcp_pypi
tests		tests
.gitignore		.gitignore
.osv-scanner.toml		.osv-scanner.toml
.pylintrc		.pylintrc
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
LICENSE-COMMERCIAL		LICENSE-COMMERCIAL
MANIFEST.in		MANIFEST.in
README.md		README.md
TOOL_DESCRIPTION_IMPROVEMENTS.md		TOOL_DESCRIPTION_IMPROVEMENTS.md
pypi.md		pypi.md
pyproject.toml		pyproject.toml
pyrefly.toml		pyrefly.toml
pytest.ini		pytest.ini
requirements.txt		requirements.txt
setup.cfg		setup.cfg

Latest commit

History

Folders and files

Repository files navigation

🐍 MCP-PyPI

✨ What is MCP-PyPI?

🎯 Key Features

🤔 Why Security Matters

🚀 Quick Start

System Requirements

Installation

Running the Server

🤖 Using with Claude Desktop

🖥️ Using with Claude Code (Terminal)

🖱️ Using with Cursor IDE

Quick Setup via Settings UI

Configuration File Setup

Configuration Example

Verification

Troubleshooting Cursor

🛠️ Available Tools

Package Discovery

Version Management

Dependency Analysis

Project Management

Statistics & Info

💡 Example Usage

🔧 Advanced Configuration

Environment Variables

Programmatic Usage

📊 Performance

🛡️ Security & Caching

Vulnerability Data Caching

Why Caching Matters

Cache Management

🖥️ CLI Usage

Help and Documentation

Package Information

Security Checks

Cache Management

❓ Troubleshooting

Common Issues

🤝 Contributing

Development Setup

📄 License

Quick License Guide:

🙏 Acknowledgments

📞 Support

About

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages