gobox-mcp

MCP server wrapping the Gobox Open API (dev-api.gobox.asia/open/api/*) for AI agents, Claude Desktop, and CLI automation.

Features

• ~40 tools covering orders, products, SKU quantities, warehouses, reports, shops, locations, consignments, Goship rates, webhooks
• 5 SKU quantity states: available, in_warehouse, keep_pick, wait_qc, wait_incoming (+ composite sku_full_status)
• Dual transport: stdio (Claude Desktop local) or SSE (Docker shared for bot/team)
• Auto token refresh with in-memory cache
• Modular: each tool group in its own file under tools/

Setup

1. Credentials

Contact Gobox admin for client_id + client_secret.

2. Install

cd gobox-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# Edit .env with your credentials

3. Run locally (stdio)

python gobox_mcp.py

4. Run in Docker (SSE)

docker compose up -d
# Test: curl http://localhost:8000/sse

Connect to Claude Desktop

Stdio mode (local)

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

{
  "mcpServers": {
    "gobox": {
      "command": "/absolute/path/to/gobox-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/gobox-mcp/gobox_mcp.py"],
      "env": {
        "GOBOX_BASE_URL": "https://dev-api.gobox.asia",
        "GOBOX_CLIENT_ID": "xxx",
        "GOBOX_CLIENT_SECRET": "xxx"
      }
    }
  }
}

SSE mode (Docker)

{
  "mcpServers": {
    "gobox": {
      "url": "http://localhost:8000/sse"
    }
  }
}

Connect to Claude Code

claude mcp add gobox \
  /absolute/path/.venv/bin/python \
  /absolute/path/gobox_mcp.py \
  -e GOBOX_BASE_URL=https://dev-api.gobox.asia \
  -e GOBOX_CLIENT_ID=xxx \
  -e GOBOX_CLIENT_SECRET=xxx

Environment switching (dev/prod)

Set GOBOX_BASE_URL to switch:

• Dev: https://dev-api.gobox.asia
• Prod: https://api.gobox.asia (verify actual prod URL)

Tool catalog

Module	Tools
orders_tools	list_orders, get_order, create_order, update_order, update_order_status, cancel_order, send_order_to_goship
products_tools	list_products, get_product, list_categories, list_brands, list_attributes, sku_quantity_available, sku_quantity_in_warehouse, sku_quantity_keep_pick, sku_quantity_wait_qc, sku_quantity_wait_incoming, sku_full_status
warehouses_tools	list_warehouses, list_inventories, list_warehouse_pickings
reports_tools	report_warehouse_import, report_warehouse_import_refund, report_export_by_order, report_export_by_sku, report_inventories, report_warehouse_store, report_warehouse_stock, report_materials
shops_tools	list_shops
locations_tools	list_cities, list_districts, list_wards, list_countries, get_sys_helpers
consignments_tools	list_consignments, get_consignment, create_consignment, cancel_consignment
goship_tools	get_shipping_rates
webhooks_tools	list_webhooks, create_webhook, update_webhook, delete_webhook, toggle_webhook

Example AI queries

"List all Gobox warehouses" "Check stock for SKU ABC123" → calls sku_full_status("ABC123") "Có bao nhiêu đơn Shopee chưa giao hôm nay?" "Báo cáo nhập kho tháng này"

Troubleshooting

OAuth fails: Verify GOBOX_GRANT_TYPE (default client_credentials). Contact admin if unsure.

FastMCP SSE DNS rebinding error: Add transport_security=TransportSecuritySettings(enable_dns_rebinding_protection=False) to mcp.run() call.

Token expired mid-call: Auto-refresh handles this. If persists, call gobox_auth.clear_cache().

Project structure

gobox-mcp/
├── gobox_mcp.py              # Main entry
├── gobox_auth.py             # OAuth token cache
├── gobox_client.py           # HTTP helper
├── tools/
│   ├── orders_tools.py
│   ├── products_tools.py
│   ├── warehouses_tools.py
│   ├── reports_tools.py
│   ├── shops_tools.py
│   ├── locations_tools.py
│   ├── consignments_tools.py
│   ├── goship_tools.py
│   └── webhooks_tools.py
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
├── .env.example
└── README.md