📦 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
| Variable | Default | Description |
|---|---|---|
TRANSPORT_MODE | stdio | Transport mode: stdio or http |
PORT | 3000 | HTTP server port (only used in http mode) |
AUTH_TOKEN | (none) | Optional authentication token for API access |
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.0requests>= 2.31.0pydantic>= 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_packagesto 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
📄 License
MIT License - See LICENSE 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 ❤️