Qvakk/python-package-mcp-server

📦 PyPI Package MCP Server

A powerful Model Context Protocol (MCP) server that enables AI assistants to fetch, explore, and analyze source code from any Python package on PyPI.

✨ Features

• 📦 Fetch Any PyPI Package: Download and explore source code from millions of packages
• 🔍 Smart File Discovery: List and filter files with intelligent code detection
• 📄 Selective Code Reading: Get specific files or entire codebases
• 🏷️ Version Control: Support for any published package version
• 🧹 Auto Cleanup: Automatic temporary file management
• 🔒 Type Safe: Full type hints with mypy support
• ⚡ Async First: Modern async/await patterns throughout
• 🤖 AI-Ready: Perfect integration with Claude, ChatGPT, and other AI assistants

🎯 Use Cases

• Code Analysis: Analyze libraries before adopting them
• Learning: Study well-written open source code
• AI Development: Enable AI assistants to understand package internals
• Documentation: Generate docs by analyzing source code
• Security Auditing: Review dependencies for security issues
• Migration Planning: Understand APIs when upgrading packages

🚀 Installation & Setup

Option 1: Local Development (Stdio Mode)

git clone https://github.com/Qvakk/pypi-package-mcp-server.git
cd pypi-package-mcp-server
pip install -e .
pypi-package-mcp-server

Option 2: Local Development (HTTP Mode)

git clone https://github.com/Qvakk/pypi-package-mcp-server.git
cd pypi-package-mcp-server
pip install -e .
TRANSPORT_MODE=http PORT=3000 pypi-package-mcp-server

Option 3: With Authentication Token

# Stdio mode with auth
AUTH_TOKEN=your-secret-token pypi-package-mcp-server

# HTTP mode with auth
TRANSPORT_MODE=http PORT=3000 AUTH_TOKEN=your-secret-token pypi-package-mcp-server

Option 4: Docker (Production - HTTP Mode)

# Build Docker image
docker build -t pypi-package-mcp-server .

# Run in stdio mode (Claude Desktop)
docker run -it pypi-package-mcp-server

# Run in HTTP mode
docker run -p 3000:3000 \
  -e TRANSPORT_MODE=http \
  -e PORT=3000 \
  pypi-package-mcp-server

# Run with authentication
docker run -p 3000:3000 \
  -e TRANSPORT_MODE=http \
  -e PORT=3000 \
  -e AUTH_TOKEN=your-secret-token \
  pypi-package-mcp-server

# Use Docker Compose
docker-compose up -d

🔧 Configuration

Environment Variables

Transport Modes

Stdio Mode (Default)

• Best for: Claude Desktop, local development
• Connection: Standard input/output streams
• Command: pypi-package-mcp-server

HTTP Mode

• Best for: Remote servers, containerized deployments
• Connection: HTTP requests on specified port
• Health endpoint: GET /health
• MCP endpoint: POST /mcp
• Command: TRANSPORT_MODE=http PORT=3000 pypi-package-mcp-server

Authentication

When AUTH_TOKEN environment variable is set, all HTTP requests must include the token in the Authorization header:

# Using Bearer token
curl -H "Authorization: Bearer your-secret-token" http://localhost:3000/health

# Or just the token
curl -H "Authorization: your-secret-token" http://localhost:3000/health

📊 Supported Packages

• ✅ All public PyPI packages
• ✅ Any published version
• ✅ Source distributions (.tar.gz)
• ✅ Binary wheels (.whl)
• ✅ Monorepo packages
• ✅ Pure Python and native extensions

🔥 Popular Packages to Explore

Try these commands with your AI assistant:

"Analyze the requests library implementation"
"Show me the Django ORM structure"
"Explore the Flask application framework"
"Review the NumPy array implementation"
"Study the pandas DataFrame code"

🛠️ Tools

1. get_pypi_package_code

Fetch source code from a Python package.

# Get all source files from the latest version
pypi_server.get_pypi_package_code(package_name="requests")

# Get a specific version
pypi_server.get_pypi_package_code(package_name="django", version="4.2.0")

# Get a specific file
pypi_server.get_pypi_package_code(
    package_name="flask",
    file_path="src/flask/app.py"
)

2. list_package_files

List all files in a package.

pypi_server.list_package_files(package_name="numpy")
pypi_server.list_package_files(package_name="pandas", version="2.0.0")

3. get_package_info

Get metadata about a package.

pypi_server.get_package_info(package_name="requests")

4. search_pypi_packages

Search for packages on PyPI.

pypi_server.search_pypi_packages(query="web framework", limit=20)

📋 Requirements

• Python 3.9 or higher
• mcp >= 0.1.0
• requests >= 2.31.0
• pydantic >= 2.0.0

🔒 Authentication (Optional)

Set the AUTH_TOKEN environment variable for API authentication:

export AUTH_TOKEN=your-secret-token
pypi-package-mcp-server

🧪 Development

Install Development Dependencies

pip install -e ".[dev]"

Run Tests

pytest

Format Code

black pypi_mcp_server/

Lint Code

ruff check pypi_mcp_server/

Type Checking

mypy pypi_mcp_server/

🐛 Troubleshooting

Package Not Found

• Verify the package name is correct (use lowercase, hyphens not underscores)
• Search first with search_pypi_packages to find the exact name

Extraction Failed

• Some packages may not have source distributions
• Check if a wheel-only package is available

Timeout Issues

• Large packages may take time to download
• Increase timeout values if needed

📚 Related Projects

• Model Context Protocol
• PyPI JSON API
• NPM Package MCP Server

📄 License

MIT License - See file for details

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

⭐ Credits

Inspired by the NPM Package MCP Server

Made with ❤️