mekayelanik/pypi-query-mcp-server

PyPI Query MCP Server

https://hub.docker.com/r/mekayelanik/pypi-query-mcp-server https://hub.docker.com/r/mekayelanik/pypi-query-mcp-server https://github.com/MekayelAnik/pypi-query-mcp-server-docker/pkgs/container/pypi-query-mcp-server https://github.com/MekayelAnik/pypi-query-mcp-server-docker/blob/main/LICENSE https://hub.docker.com/r/mekayelanik/pypi-query-mcp-server https://github.com/MekayelAnik/pypi-query-mcp-server-docker/stargazers https://github.com/MekayelAnik/pypi-query-mcp-server-docker/forks https://github.com/MekayelAnik/pypi-query-mcp-server-docker/issues https://github.com/MekayelAnik/pypi-query-mcp-server-docker/commits/main

Multi-Architecture Docker Image for PyPI Package Query, Dependency Analysis & Download Stats

---

📋 Table of Contents

• Overview
• Supported Architectures
• Available Tags
• Quick Start
• Configuration
• MCP Client Configuration
• Network Configuration
• Updating
• Troubleshooting
• Additional Resources
• Support & License
• Major Changes

---

😎 Buy Me a Coffee ☕︎

Your support encourages me to keep creating/supporting my open-source projects. If you found value in this project, you can buy me a coffee to keep me inspired.

Overview

PyPI Query MCP Server queries the Python Package Index — package metadata, version lists, dependency trees, Python compatibility checks, download statistics, and trending packages — through the Model Context Protocol. Built on the upstream https://github.com/loonghao/pypi-query-mcp-server (MIT-licensed) and packaged here under GPL-3.0; this image is independently maintained and is not affiliated with the upstream project. The container uses https://github.com/sparfenyuk/mcp-proxy as the stdio<->HTTP/SSE bridge (replacing supergateway in stateful mode by default).

Key Features

✨ Multi-Architecture Support - Native support for x86-64 and ARM64
🚀 Multiple Transport Protocols - StreamableHTTP and SSE via mcp-proxy
🔒 Secure by Design - Alpine-based with minimal *** surface
⚡ High Performance - ZSTD compression for faster deployments
🎯 Production Ready - Stable releases with comprehensive testing
🔧 Easy Configuration - Simple environment variable setup

---

Supported Architectures

💡 Multi-arch images automatically select the correct architecture for your system.

---

Available Tags

System Requirements

• Docker Engine: 23.0+
• RAM: Minimum 512MB
• CPU: Single core sufficient

🔒 CRITICAL: Do NOT expose this container directly to the internet without proper security measures (reverse proxy, SSL/TLS, authentication, firewall rules).

---

Quick Start

Docker Compose (Recommended)

yaml
services:
  pypi-query-mcp-server:
    image: mekayelanik/pypi-query-mcp-server:stable
    container_name: pypi-query-mcp-server
    restart: unless-stopped
    ports:
      - "8055:8055"
    volumes:
      - pypi-query-mcp-cache:/home/node/.cache   # Persist cache for future embedding support
    environment:
      - PORT=8055
      - INTERNAL_PORT=38056
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Dhaka
      - NODE_ENV=production
      - PROTOCOL=HTTP
      - ENABLE_HTTPS=false
      - HTTP_VERSION_MODE=auto
      # Optional: require Bearer token auth at HAProxy layer
      # - API_KEY=replace-with-strong-secret
    hostname: pypi-query-mcp-server
    domainname: local

volumes:
  pypi-query-mcp-cache:
    driver: local

Deploy:

bash
docker compose up -d
docker compose logs -f pypi-query-mcp-server

Docker CLI

bash
docker volume create pypi-query-mcp-cache
docker run -d \
  --name=pypi-query-mcp-server \
  --restart=unless-stopped \
  -p 8055:8055 \
  -v pypi-query-mcp-cache:/home/node/.cache \
  -e PORT=8055 \
  -e INTERNAL_PORT=38056 \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Asia/Dhaka \
  -e NODE_ENV=production \
  -e PROTOCOL=HTTP \
  -e ENABLE_HTTPS=false \
  -e HTTP_VERSION_MODE=auto \
  mekayelanik/pypi-query-mcp-server:stable

Access Endpoints

When HTTPS is enabled (ENABLE_HTTPS=true), use TLS endpoints:

WebSocket transport was dropped in the migration to mcp-proxy. Setting PROTOCOL=WS will now fail at startup with a clear message. Use SHTTP or SSE instead.

⚠️ Security Warning: The container now defaults to HTTP (ENABLE_HTTPS=false) for easier local setup. Use ENABLE_HTTPS=true for production, public networks, or any untrusted environment.

⏱️ ARM Devices: Allow 30-60 seconds for initialization before accessing endpoints.

---

Configuration

Environment Variables

HTTPS and HTTP Version Notes

• If ENABLE_HTTPS=true and cert files are missing, the container auto-generates a self-signed certificate.
• If TLS_CERT_PATH and TLS_KEY_PATH exist, they are merged into TLS_PEM_PATH and used directly.
• HTTP_VERSION_MODE=h3 (or auto) enables HTTP/3 only when HAProxy build includes QUIC; otherwise it safely falls back.

API Key Authentication Notes

• Set API_KEY to enforce authentication at reverse proxy level.
• Expected header format: Authorization: Bearer <API_KEY>.
• Localhost health checks remain accessible for liveness/readiness.

Rate Limiting and IP Access Control

• Rate limiting: Set RATE_LIMIT=100 to allow 100 requests per RATE_LIMIT_PERIOD (default 10s) per IP. Exceeding the limit returns HTTP 429 with a Retry-After header.
• Connection limiting: Set MAX_CONNECTIONS_PER_IP=50 to cap concurrent connections per IP. Exceeding returns HTTP 429.
• IP blocklist: Set IP_BLOCKLIST=192.0.2.0/24,198.51.100.5 to block specific IPs/CIDRs. Blocked IPs receive HTTP 403.
• IP allowlist: Set IP_ALLOWLIST=10.0.0.0/8,192.168.1.0/24 to allow only listed IPs/CIDRs. All others receive HTTP 403. Localhost is always allowed.
• All features default to disabled. Combine as needed — blocklist is checked before allowlist.

Memory & Concurrency Tuning

mcp-proxy runs the PyPI Query backend as a single long-lived stdio child and multiplexes all client sessions through it via JSON-RPC ids. This caps the expected memory footprint; the knobs below cap the worst case:

• MCP_PROXY_STATELESS=false (default) — share one backend child across all sessions. Recommended for almost every deployment. Flip to true only when you genuinely need per-request isolation (and accept the per-request transport-instance cost).
• PQMS_MAX_MEM_MB=1024 — caps the virtual-memory size of the pypi-query child via prlimit --as. A runaway backend gets OOM-killed by the kernel before it exhausts the host. The recommended starting value is 1 GiB.
• HAPROXY_FRONTEND_MAXCONN=64 + HAPROXY_SERVER_MAXCONN=16 — bound concurrent connections at the HAProxy layer so a burst cannot saturate the upstream stdio bridge.
• /healthz is answered directly by HAProxy with a local 200 — Docker's container healthcheck no longer depends on upstream MCP readiness.

User & Group IDs

Find your IDs and set them to avoid permission issues:

bash
id username
# uid=1000(user) gid=1000(group)

Timezone Examples

yaml
- TZ=Asia/Dhaka        # Bangladesh
- TZ=America/New_York  # US Eastern
- TZ=Europe/London     # UK
- TZ=UTC               # Universal Time

---

MCP Client Configuration

Transport Support

WebSocket transport was dropped in the migration to mcp-proxy.

---

VS Code (Cline/Roo-Cline)

Configure in .vscode/settings.json:

json
{
  "mcp.servers": {
    "pypi-query-mcp-server": {
      "url": "http://host-ip:8055/mcp",
      "transport": "http"
    }
  }
}

---

Claude Desktop App/Claude Code

Configuration:

With API_KEY

claude mcp add-json github '{"type":"http","url":"http://localhost:8055/mcp","headers":{"Authorization":"Bearer <YOUR_API_KEY>"}}'

Without API_KEY

claude mcp add-json github '{"type":"http","url":"http://localhost:8055/mcp"}'

---

Codex CLI

Configure in ~/.codex/config.json:

json
{
  "mcpServers": {
    "pypi-query-mcp-server": {
      "transport": "http",
      "url": "http://host-ip:8055/mcp"
    }
  }
}

---

Codeium (Windsurf)

Configure in .codeium/mcp_settings.json:

json
{
  "mcpServers": {
    "pypi-query-mcp-server": {
      "transport": "http",
      "url": "http://host-ip:8055/mcp"
    }
  }
}

---

Cursor

Configure in ~/.cursor/mcp.json:

json
{
  "mcpServers": {
    "pypi-query-mcp-server": {
      "transport": "http",
      "url": "http://host-ip:8055/mcp"
    }
  }
}

---

Testing Configuration

Verify with https://github.com/modelcontextprotocol/inspector:

bash
npm install -g @modelcontextprotocol/inspector
mcp-inspector http://host-ip:8055/mcp

---

Network Configuration

Comparison

---

Bridge Network (Default)

yaml
services:
  pypi-query-mcp-server:
    image: mekayelanik/pypi-query-mcp-server:stable
    ports:
      - "8055:8055"

Benefits: Container isolation, easy setup, works everywhere Access: http://localhost:8055/mcp

---

Host Network (Linux Only)

yaml
services:
  pypi-query-mcp-server:
    image: mekayelanik/pypi-query-mcp-server:stable
    network_mode: host

Benefits: Maximum performance, no NAT overhead, no port mapping needed ***ations: Linux only, shares host network namespace Access: http://localhost:8055/mcp

---

MACVLAN Network (Advanced)

yaml
services:
  pypi-query-mcp-server:
    image: mekayelanik/pypi-query-mcp-server:stable
    mac_address: "AB:BC:CD:DE:EF:01"
    networks:
      macvlan-net:
        ipv4_address: 192.168.1.100

networks:
  macvlan-net:
    driver: macvlan
    driver_opts:
      parent: eth0
    ipam:
      config:
        - subnet: 192.168.1.0/24
          gateway: 192.168.1.1

Benefits: Dedicated IP, direct LAN access ***ations: Linux only, requires additional setup Access: http://192.168.1.100:8055/mcp

---

Updating

Docker Compose

bash
docker compose pull
docker compose up -d
docker image prune -f

Docker CLI

bash
docker pull mekayelanik/pypi-query-mcp-server:stable
docker stop pypi-query-mcp-server && docker rm pypi-query-mcp-server
# Run your original docker run command
docker image prune -f

One-Time Update with Watchtower

bash
docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower \
  --run-once \
  pypi-query-mcp-server

---

Troubleshooting

Pre-Flight Checklist

• ✅ Docker Engine 23.0+
• ✅ Port 8055 available
• ✅ Sufficient startup time (ARM devices)
• ✅ Latest stable image
• ✅ Correct configuration

Common Issues

Container Won't Start

bash
# Check Docker version
docker --version

# Verify port availability
sudo netstat -tulpn | grep 8055

# Check logs
docker logs pypi-query-mcp-server

Permission Errors

bash
# Get your IDs
id $USER

# Update configuration with correct PUID/PGID
# Fix volume permissions if needed
sudo chown -R 1000:1000 /path/to/volume

Client Cannot Connect

bash
# Test connectivity
curl http://localhost:8055/mcp
curl http://host-ip:8055/mcp
curl -k https://localhost:8055/mcp
curl -k https://host-ip:8055/mcp

# Check firewall
sudo ufw status

# Verify container
docker inspect pypi-query-mcp-server | grep IPAddress

Slow ARM Performance

• Wait 30-60 seconds after start
• Monitor: docker logs -f pypi-query-mcp-server
• Check resources: docker stats pypi-query-mcp-server
• Use faster storage (SSD vs SD card)

Debug Information

When reporting issues, include:

bash
# System info
docker --version && uname -a

# Container logs
docker logs pypi-query-mcp-server --tail 200 > logs.txt

# Container config
docker inspect pypi-query-mcp-server > inspect.json

---

Additional Resources

Documentation

• 📚 https://github.com/loonghao/pypi-query-mcp-server
• 📦 https://pypi.org/project/pypi-query-mcp-server/
• 🌉 https://github.com/sparfenyuk/mcp-proxy
• 🔧 https://github.com/modelcontextprotocol/inspector

Docker Resources

• 🐳 https://docs.docker.com/compose/production/
• 🌐 https://docs.docker.com/network/
• 🛡️ https://docs.docker.com/engine/security/

Monitoring

• 📊 https://crazymax.dev/diun/
• ⚡ https://containrrr.dev/watchtower/

---

😎 Buy Me a Coffee ☕︎

Your support encourages me to keep creating/supporting my open-source projects. If you found value in this project, you can buy me a coffee to keep me inspired.

Support & License

Getting Help

Docker Image Issues:

• GitHub: https://github.com/MekayelAnik/pypi-query-mcp-server-docker/issues

PyPI Query MCP Server Issues:

• GitHub: https://github.com/loonghao/pypi-query-mcp-server/issues
• Website: https://github.com/loonghao/pypi-query-mcp-server/

Contributing

We welcome contributions:

1. Report bugs via GitHub Issues
2. Suggest features
3. Improve documentation
4. Test beta releases

License

GPL License. See https://raw.githubusercontent.com/MekayelAnik/pypi-query-mcp-server-docker/refs/heads/main/LICENSE for details.

PyPI Query MCP Server server has its own license - see https://github.com/loonghao/pypi-query-mcp-server.

---

Major Changes

• Initial Release: Full CI/CD pipeline with HAProxy, HTTPS/TLS, QUIC/HTTP3, API key auth