Allows managing Shopee orders, products, and reporting through the Gobox platform.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@gobox-mcp List all Gobox warehouses"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server wrapping the Gobox Open API (dev-api.gobox.asia/open/api/*) for AI agents, Claude Desktop, and CLI automation.
~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/
Related MCP server: commercetools Commerce MCP
Contact Gobox admin for client_id + client_secret.
cd gobox-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# Edit .env with your credentialspython gobox_mcp.pydocker compose up -d
# Test: curl http://localhost:8000/sseEdit ~/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"
}
}
}
}{
"mcpServers": {
"gobox": {
"url": "http://localhost:8000/sse"
}
}
}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=xxxSet GOBOX_BASE_URL to switch:
Dev: https://dev-api.gobox.asia
Prod: https://api.gobox.asia (verify actual prod URL)
Module | Tools |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
"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"
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().
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.mdAdd attachment files to a consignment.
Inputs: code (required), files (required). Returns: object
Cancel a consignment. Only works for draft/confirmed status.
Inputs: code (required), reason. Returns: object
Cancel an order. Only works before shipping stage.
Inputs: transaction_no (required), reason. Returns: object
Create a new consignment (nhập hàng vào kho).
WORKFLOW: First call list_warehouses to get warehouse_id, then get_product to verify SKUs.
Inputs: warehouse_id (required), status (required), products (required), qc_type, +4 more. Returns: object
Create a new order.
WORKFLOW: First verify product stock with sku_quantity_available. See WORKFLOW GUIDE in module docstring for full creation flow.
Inputs: data (required). Returns: object
Create a new product.
WORKFLOW: First call list_categories + list_brands to get valid IDs.
Required body fields: category_id (int): Category ID (from list_categories) Optional fields: name (str), sku (str), description (str), brand_id (int), weight (int, grams), length/width/height (int), is_combo (bool), total_price (number, required if is_combo=1), product_combos: [{sku_name, quantity}] (if combo), variants: [{name, value}], skus: [{sku, price, supplier_price, variants}], images: [{image, variant_name, variant_value}], attributes: [{attribute_id, value, platform, values[], unit}]
Inputs: data (required). Returns: object
Register a new webhook endpoint.
Inputs: url (required), events (required). Returns: object
Delete product by SKU. WARNING: This is irreversible.
Inputs: sku (required). Returns: object
Delete a webhook subscription.
Inputs: webhook_id (required). Returns: object
Fetch full consignment detail by code.
Inputs: code (required), include. Returns: object
Fetch full order detail by transactionNo.
Inputs: transaction_no (required). Returns: object
Fetch FULL product detail by SKU with all relations.
Inputs: sku (required), include. Returns: object
Fetch Goship carrier rates for a delivery route.
Inputs: address (required), warehouse_id, cod, amount, +4 more. Returns: object
Fetch system enum/status reference (order statuses, types, etc.).
Call this once to let AI understand what status codes mean when interpreting order/inventory responses.
Inputs: no named parameters. Returns: object
List product attributes for a category. category_id is REQUIRED.
WORKFLOW: Call list_categories first to get category_id.
Inputs: category_id (required). Returns: object
List brands for a category. category_id is REQUIRED.
WORKFLOW: Call list_categories first to get category_id.
Inputs: category_id (required). Returns: object
List all product categories. Use to get category_id for product creation.
WORKFLOW: Call this FIRST, then use category_id for list_brands and list_attributes.
Inputs: no named parameters. Returns: object
List all Vietnamese provinces/cities.
Inputs: no named parameters. Returns: object
List consignment documents. Returns paginated results.
IMPORTANT for AI:
Use 'q' to search by consignment code.
Use 'include' for relations: warehouse,skus,attachments
Status: 0=draft, 2=confirmed, 3=received, 4=partially imported, 5=imported, 49=cancelled
Inputs: q, status, warehouse_id, start_create_date, +6 more. Returns: object
List all countries supported by Gobox.
Inputs: no named parameters. Returns: object
List districts for a city. city_id is REQUIRED.
WORKFLOW: Call list_cities first to get city_id.
Inputs: city_id (required). Returns: object
List inventory check (kiểm kho) documents. Paginated.
IMPORTANT for AI:
Status: 1=pending, 10=awaiting confirmation, 200=completed
Done status: 1=matched, 2=discrepancy, 3=excess, 4=shortage
Use date filters + warehouse_id to narrow results.
Include: location,confirmer,creator,processer,sku
Inputs: q, warehouse_id, status, done_status, +9 more. Returns: object
List orders with filters. Returns paginated results.
IMPORTANT for AI:
Use 'q' to search by order code, transaction number, or tracking number.
Use date range filters to narrow results.
Response 'meta.pagination' has total, total_pages, current_page for pagination.
Inputs: q, status, shop_id, warehouse_id, +6 more. Returns: object
List products with filters. Returns paginated results.
IMPORTANT for AI:
ALWAYS use 'q' to search by name/SKU first instead of browsing all pages.
Use 'include' to get relations: skus,variants,images,attributes,brand,shops,combos
Response 'meta.pagination' has total, total_pages, current_page for pagination.
Platform codes: 1=shopee, 2=lazada, 3=tiktokshop, 4=tiki, 5=pancake, 6=pos
Inputs: q, category_id, brand_id, shop_ids, +7 more. Returns: object
List all product SKU variants.
Inputs: q, limit, page. Returns: object
List all connected e-commerce shops.
Inputs: q, limit, page. Returns: object
List wards for a district. district_id is REQUIRED.
WORKFLOW: Call list_cities → list_districts(city_id) → list_wards(district_id).
Inputs: district_id (required). Returns: object
List warehouse picking documents (nhập/xuất/chuyển kho). Paginated.
IMPORTANT for AI:
Type: 1=shelf transfer, 2=import, 3=export, 4=warehouse transfer
Use 'q' to search by code, order number, or shipping code.
Include: moves.sku,order,processer,doner,handoverer,handover,assigner,waiting_revoker,revoker
Inputs: q, warehouse_id, warehouse_dest_id, type, +10 more. Returns: object
List all warehouses.
Inputs: q, include, limit, page. Returns: object
List all registered webhook subscriptions.
Inputs: no named parameters. Returns: object
Warehouse export report grouped by order.
Inputs: start_date, end_date, warehouse_id, q, +3 more. Returns: object
Warehouse export report grouped by SKU.
Inputs: start_date, end_date, warehouse_id, sku_sku, +3 more. Returns: object
Inventory check (kiểm kho) report.
Inputs: start_date, end_date, warehouse_id, sku_sku, +5 more. Returns: object
Materials (packaging, supplies) usage report.
Inputs: start_date, end_date, warehouse_id, q, +3 more. Returns: object
Warehouse import (stock-in) report.
Inputs: start_date, end_date, warehouse_id, sku_sku, +5 more. Returns: object
Import report for refund/returned stock.
Inputs: start_date, end_date, warehouse_id, sku_sku, +4 more. Returns: object
Current stock balance per warehouse/SKU. warehouse_id is REQUIRED.
Inputs: warehouse_id (required), start_date, end_date, sku_sku, +1 more. Returns: object
Warehouse storage snapshot — what's currently stored.
Inputs: start_date, end_date, warehouse_id, sku_sku, +3 more. Returns: object
Fetch ALL consignments across all pages in parallel.
ALWAYS use filters to narrow results.
Inputs: q, status, warehouse_id, start_create_date, +2 more. Returns: object
Fetch ALL inventory checks across all pages in parallel.
ALWAYS use filters to narrow results.
Inputs: warehouse_id, status, done_status, include, +2 more. Returns: object
Fetch ALL orders across all pages in parallel.
Use for reporting/counting, e.g. 'all orders from last week'. ALWAYS use filters to narrow results.
Inputs: q, status, shop_id, warehouse_id, +2 more. Returns: object
Fetch ALL products across all pages in parallel.
Use when you need a complete list, e.g. 'show all products of brand X'. ALWAYS use q/category/brand filters to narrow results when possible.
Inputs: q, category_id, brand_id, include. Returns: object
Fetch ALL product SKU variants across all pages in parallel.
Inputs: q. Returns: object
Fetch ALL shops across all pages in parallel.
Inputs: no named parameters. Returns: object
Fetch ALL warehouse pickings across all pages in parallel.
ALWAYS use filters to narrow results.
Inputs: warehouse_id, type, status, include, +2 more. Returns: object
Fetch ALL warehouses across all pages in parallel.
Inputs: include. Returns: object
Send order to warehouse (Gobox) for packing.
WORKFLOW: Call this AFTER create_order, BEFORE send_order_to_goship. This triggers the warehouse to start picking and packing the order.
Inputs: transaction_no (required). Returns: object
Send order to carrier (Goship) for delivery.
WORKFLOW: Call this AFTER send_order_to_gobox (order must be packed first). This triggers carrier pickup/delivery scheduling.
Inputs: transaction_no (required). Returns: object
Composite: fetch ALL 5 quantity states for a single SKU in parallel.
PREFERRED tool for answering 'How much of SKU X do we have?' Returns all states in one call instead of 5 sequential calls.
Inputs: sku (required). Returns: object
Get AVAILABLE (sellable) quantity. This is what can be sold NOW.
Inputs: sku. Returns: object
Get total quantity physically IN warehouse (includes held stock).
Inputs: sku. Returns: object
Get quantity reserved for outgoing order picks (not available for sale).
Inputs: sku. Returns: object
Get quantity expected from incoming consignments (not yet in warehouse).
Inputs: sku. Returns: object
Get quantity waiting for QC inspection (not yet sellable).
Inputs: sku. Returns: object
Enable/disable a webhook.
Inputs: webhook_id (required). Returns: object
Update order fields by transactionNo.
WORKFLOW: Call get_order first to see current state.
Inputs: transaction_no (required), data (required). Returns: object
Update order status. Call get_sys_helpers() for valid status values.
Inputs: transaction_no (required), status (required). Returns: object
Update product by SKU.
WORKFLOW: Call get_product(sku) first to see current state before updating. Body fields same as create_product.
Inputs: sku (required), data (required). Returns: object
Update webhook configuration.
Inputs: webhook_id (required), data (required). Returns: object
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 59 tools
Every tool targets a distinct operation or resource, with clear descriptions and workflow notes that prevent confusion. Overlapping concepts like list_consignments vs search_all_consignments are clearly differentiated by scope.
Tool names follow a consistent verb_noun pattern (e.g., list_warehouses, create_order, get_product, delete_webhook). Variations like sku_full_status and toggle_webhook still adhere to the same style, ensuring predictability.
59 tools is high but justified by the comprehensive domain coverage (products, orders, consignments, inventory, reports, webhooks, etc.). Each tool serves a specific need, though some consolidation could reduce the count without loss of clarity.
The tool set covers the full lifecycle of key entities (CRUD for products, orders, consignments; status checks; reports; shipping workflow) with no obvious gaps. Workflow hints ensure agents can chain operations correctly.
Connect AI to store orders, products and inventory with scoped access and human approvals.
Launch and manage online stores with AI agents: products, inventory, pricing, orders and promotions.
Manage your NanoCart store from any AI agent: products, orders, coupons, subscribers, reports.
Run storefronts, listings, orders, content, fulfillment, and analytics through AI.
