BuyWhere
← Back to documentation

mcp-deployment

MCP Server Deployment Guide

Self-host the BuyWhere MCP server for AI agent integrations.

Table of Contents

Prerequisites

  • Python 3.10 or higher
  • pip or pip3
  • A BuyWhere API key (get one)
  • Linux, macOS, or Windows

Local Setup

1. Clone or navigate to the repository

git clone https://github.com/buywhere/buywhere-api.git
cd buywhere-api

2. Create a virtual environment (recommended)

python3 -m venv venv
source venv/bin/activate   # Linux/macOS
# venv\Scripts\activate    # Windows

3. Install dependencies

pip install -r requirements.txt

Required packages:

  • httpx — async HTTP client
  • mcp — Model Context Protocol server framework
  • fastapi — web framework
  • uvicorn — ASGI server

4. Configure environment variables

Create a .env file or export variables:

# Required
export BUYWHERE_API_KEY="your_api_key_here"

# Optional (defaults shown)
export BUYWHERE_API_URL="http://localhost:8000"
export BUYWHERE_MCP_HTTP_PORT="8080"

5. Run the MCP server

STDIO transport (default, recommended for desktop agents like Claude Desktop):

python mcp_server.py

HTTP/SSE transport (for web or cloud deployments):

python mcp_server.py --transport http --port 8080

Both transports:

python mcp_server.py --transport both --port 8080

6. Verify it is running

# Health check
curl http://localhost:8080/health   # if using HTTP transport

# Or test via STDIO by running:
echo '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}' | python mcp_server.py

Docker Deployment

Using Docker directly

docker build -t buywhere-mcp .

docker run -d \
  --name buywhere-mcp \
  -p 8080:8080 \
  -e BUYWHERE_API_KEY="your_api_key_here" \
  -e BUYWHERE_API_URL="https://api.buywhere.ai" \
  -e BUYWHERE_MCP_HTTP_PORT=8080 \
  buywhere-mcp

Using Docker Compose

Create a docker-compose.mcp.yml:

version: '3.8'

services:
  buywhere-mcp:
    build: .
    container_name: buywhere-mcp
    ports:
      - "8080:8080"
    environment:
      - BUYWHERE_API_KEY=${BUYWHERE_API_KEY}
      - BUYWHERE_API_URL=${BUYWHERE_API_URL:-https://api.buywhere.ai}
      - BUYWHERE_MCP_HTTP_PORT=8080
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3

Run:

docker compose -f docker-compose.mcp.yml up -d

Production Docker considerations

  • Store BUYWHERE_API_KEY in a secrets manager, not in plaintext
  • Use a reverse proxy (nginx) for TLS termination if exposing HTTP transport publicly
  • Set resource limits: --memory="512m" --cpus="1"
  • Use --env-file to load environment variables from a file excluded from version control

Environment Variables

VariableRequiredDefaultDescription
BUYWHERE_API_KEYYes—Your BuyWhere API key
BUYWHERE_API_URLNohttp://localhost:8000BuyWhere API base URL
BUYWHERE_MCP_HTTP_PORTNo8080HTTP/SSE server port

Getting an API key

  1. Sign up at https://buywhere.ai/api
  2. Navigate to Dashboard > API Keys
  3. Create a new key with appropriate scopes
  4. Copy the key — it will not be shown again

Security best practices

  • Never commit API keys to version control
  • Use a secrets manager (AWS Secrets Manager, HashiCorp Vault, etc.) in production
  • Rotate keys periodically
  • Use environment-specific keys (dev/staging/prod)

Troubleshooting

"Connection refused" errors

  1. Verify the MCP server is running: 
    curl http://localhost:8080/health
  2. Check the API URL is correct (must include https://api.buywhere.ai)
  3. Ensure your firewall allows the port

"Permission denied" or 401 errors

  1. Confirm your API key is valid and active
  2. Check if you've exceeded your rate limit
  3. Verify the API key has the required scopes

MCP server not appearing in Claude Desktop

  1. Use absolute paths to mcp_server.py, not relative paths
  2. Restart Claude Desktop completely after config changes
  3. Check Claude's developer console for error messages:
    • macOS: ~/Library/Logs/Claude/
    • Linux: ~/.config/Claude/logs/
    • Windows: %APPDATA%\Claude\logs\

Python import errors

Ensure all dependencies are installed:

pip install -r requirements.txt

If using a virtual environment, make sure it is activated.

Docker container exits immediately

Check logs:

docker logs buywhere-mcp

Common issues:

  • Missing BUYWHERE_API_KEY environment variable
  • Port already in use — try a different port
  • Invalid API URL format (must include http:// or https://)

High memory usage

  • Limit Docker container memory: --memory=512m
  • Reduce the number of concurrent connections
  • Use HTTP transport instead of STDIO for long-running deployments

Testing with Claude Desktop

1. Configure Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Linux: ~/.config/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the BuyWhere MCP server:

{
  "mcpServers": {
    "buywhere": {
      "command": "python",
      "args": [
        "/absolute/path/to/buywhere-api/mcp_server.py"
      ],
      "env": {
        "BUYWHERE_API_KEY": "your_api_key_here",
        "BUYWHERE_API_URL": "https://api.buywhere.ai"
      }
    }
  }
}

2. Restart Claude Desktop

Close completely and reopen.

3. Verify the connection

Ask Claude:

Search for "iphone 15 pro" on BuyWhere

You should see product results from Singapore e-commerce platforms.

4. Check available tools

Ask Claude:

What tools do you have available from BuyWhere?

Claude should list: search_products, get_product, compare_products, get_deals, list_categories.

Quick Reference

# One-liner local test
BUYWHERE_API_KEY=your_key python mcp_server.py --transport http --port 8080

# Docker deployment
docker run -d -p 8080:8080 -e BUYWHERE_API_KEY=your_key buywhere-mcp

# Check logs
docker logs -f buywhere-mcp

# Stop
docker stop buywhere-mcp

Support