PyPI Package MCP Server

# 📦 PyPI Package MCP Server [](https://www.python.org/) [](https://opensource.org/licenses/MIT) > 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) ```bash 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) ```bash 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 ```bash # 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) ```bash # 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: ```bash # 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. ```python # 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. ```python 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. ```python pypi_server.get_package_info(package_name="requests") ``` ### 4. `search_pypi_packages` Search for packages on PyPI. ```python 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: ```bash export AUTH_TOKEN=your-secret-token pypi-package-mcp-server ``` ## 🧪 Development ### Install Development Dependencies ```bash pip install -e ".[dev]" ``` ### Run Tests ```bash pytest ``` ### Format Code ```bash black pypi_mcp_server/ ``` ### Lint Code ```bash ruff check pypi_mcp_server/ ``` ### Type Checking ```bash 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](https://github.com/modelcontextprotocol/servers) - [PyPI JSON API](https://warehouse.pypa.io/api-reference/json.html) - [NPM Package MCP Server](https://github.com/Qvakk/npm-package-mcp-server) ## 📄 License MIT License - See [LICENSE](LICENSE) file for details ## 🤝 Contributing Contributions are welcome! Please feel free to submit a Pull Request. ## ⭐ Credits Inspired by the [NPM Package MCP Server](https://github.com/Qvakk/npm-package-mcp-server) --- **Made with ❤️**