📦 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.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

📄 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 ❤️