Developers

AI assistants (MCP)

Connect Claude, ChatGPT or Cursor to your NinjaBuy account and ask in plain words: where an order is, what is on your shelf, whether a listing is worth selling, and put it on your store.

On this page

1Connect
2Sign-in and access
3Nothing here spends money
4Tools
5What to ask

Connect

One server address for every assistant. You sign in with your NinjaBuy account; there is no key to paste.

https://www.ninjabuy.com/mcp

Claude

Open Settings › Connectors and choose Add custom connector.
Paste the address above and add it.
Sign in with your NinjaBuy phone number, then choose Allow access.

ChatGPT

Turn on developer mode in Settings, then add a custom MCP server.
Paste the address above and choose OAuth as the sign-in.
Sign in with your NinjaBuy phone number, then choose Allow access.

Cursor

Add the server under Cursor Settings › MCP, or in ~/.cursor/mcp.json. Cursor opens the NinjaBuy sign-in in your browser the first time.

~/.cursor/mcp.json

{
  "mcpServers": {
    "ninjabuy": {
      "url": "https://www.ninjabuy.com/mcp"
    }
  }
}

Claude Code and other command-line assistants

Terminal

claude mcp add --transport http ninjabuy https://www.ninjabuy.com/mcp

Menu names change as the assistants update; look for “custom connector” or “custom MCP server”.

The assistant signs in with OAuth 2.1: it registers itself, sends you to ninjabuy.com, and you approve it on our own screen, which names the app and where it will send you back. Only allow an app you just asked to connect. You approve each app once.

It acts as your account: the tools take no account id, and see only your orders, shelf and products.
Access lasts an hour and renews for seven days; then the assistant asks you to sign in again.
Remove the connector in your assistant to disconnect it.
The tools that read a marketplace (product, analyze_product, import_product, push_to_shopify) share the API's 30-a-minute window: Rate limits.

Nothing here spends money

No tool pays, places a shipment or spends your balance. When something needs paying, the answer names the page where you do it: checkout from the cart, shipping from your warehouse page. push_to_shopify lists a product as a draft, so nothing goes on sale until you publish it.

Tools

Every answer carries requestId (quote it when you write to us) and warnings, things worth knowing that did not stop the call. A long answer is cut at about 6,000 tokens with truncated: true; lists then take a smaller limit.

Tool	What it does
list_orders	List my NinjaBuy orders
order	One NinjaBuy order
warehouse	My NinjaBuy warehouse
product	Read a product's variants
add_to_cart	Add to my NinjaBuy cart
search_products	Search products
analyze_product	Analyse a product
import_product	Import a product
push_to_shopify	Push to Shopify
list_synced_products	List my synced products
set_sync_rule	Set a sync rule

`list_orders`read-only

The account's orders, newest first: status, payment status, what is still owed, the items and each order's page. Follow cursor while has_more is true.

cursorstring?: From the previous answer; leave out for the first page.
limitnumber?: 1 to 25. 25 when left out.

list_orders answers

{
  "orders": [
    {
      "id": "j57a9x2b",
      "number": 1012,
      "kind": "procurement",
      "total": "¥57.00",
      "orderStatus": { "status": "ordered" },
      "paymentStatus": { "status": "paid" },
      "amountDue": null,
      "itemCount": 1,
      "items": [
        {
          "id": "P1012-1",
          "title": "Heavyweight washed hoodie",
          "quantity": 1,
          "options": ["Black", "M"],
          "status": "ordered"
        }
      ],
      "url": "https://www.ninjabuy.com/me/orders/j57a9x2b"
    }
  ],
  "cursor": "eyJvIjoyNX0",
  "has_more": true,
  "requestId": "5f7c2a1e-3b8d-4c61-9a0f-2e4d6b8c1a37",
  "warnings": []
}

`order`read-only

One order by id: its lines and prices, each item's status and how many arrived, and the shipment with tracking. order is null for an id that is not this account's.

idstringrequired: An id from list_orders.

order answers

{
  "order": {
    "id": "j57c4k1m",
    "number": 1019,
    "kind": "shipout",
    "orderStatus": { "status": "ready" },
    "paymentStatus": { "status": "paid" },
    "shipment": {
      "state": "shipped",
      "destinationCountry": "US",
      "weightGrams": 176,
      "trackingNumbers": ["YT2630812345678"],
      "shippedAt": 1793685600000
    },
    "url": "https://www.ninjabuy.com/me/orders/j57c4k1m"
  },
  "requestId": "5f7c2a1e-3b8d-4c61-9a0f-2e4d6b8c1a37",
  "warnings": []
}

`warehouse`read-only

Everything that arrived at our warehouse: photos, how many arrived, can ship or are in a shipment, weight, declared value, whether it is paid for, and when free storage ends.

No inputs.

warehouse answers

{
  "items": [
    {
      "id": "P1012-1",
      "order": 1012,
      "title": "Heavyweight washed hoodie",
      "photos": [
        {
          "type": "image",
          "url": "https://media.ninjabuy.com/qc/P1012-1/1.webp"
        }
      ],
      "received": 1,
      "availableToShip": 1,
      "inShipment": 0,
      "unitWeightGrams": 176,
      "declaredUnitValue": "¥38.00",
      "paid": true,
      "freeStorageUntil": "2026-12-02T03:20:11.000Z"
    }
  ],
  "warehouseUrl": "https://www.ninjabuy.com/me/warehouse",
  "requestId": "5f7c2a1e-3b8d-4c61-9a0f-2e4d6b8c1a37",
  "warnings": []
}

`product`read-only

Reads a listing from any product link (Taobao, Tmall, Weidian, 1688, another shopping agent's link or short link, or a NinjaBuy product page): title, pictures, seller, and every variant with its skuId, label, CN¥ price and stock.

linkstringrequired: A product link, up to 2,048 characters.

product answers

{
  "product": {
    "handle": "weidian-7750970856",
    "title": "重磅水洗连帽卫衣",
    "seller": "Ruoyi Studio",
    "variants": [
      {
        "skuId": "5187209554",
        "label": "Black / M",
        "priceMinor": 3800,
        "price": "¥38.00",
        "inStock": true
      },
      {
        "skuId": "5187209555",
        "label": "Black / L",
        "priceMinor": 3800,
        "price": "¥38.00",
        "inStock": false
      }
    ],
    "url": "https://www.ninjabuy.com/products/weidian-7750970856"
  },
  "requestId": "5f7c2a1e-3b8d-4c61-9a0f-2e4d6b8c1a37",
  "warnings": []
}

`add_to_cart`writes

Puts variants of one listing in the cart, to buy ahead and keep on your shelf. Nothing is bought: the answer is the cart page, where you check out.

handlestringrequired: From product.
lines{ skuId, quantity }[]required: 1 to 100 lines; quantity 1 to 9,999. A variant already in the cart adds to it.

add_to_cart answers

{
  "added": 1,
  "cartUrl": "https://www.ninjabuy.com/cart",
  "requestId": "5f7c2a1e-3b8d-4c61-9a0f-2e4d6b8c1a37",
  "warnings": []
}

`search_products`read-only

Keyword search on Taobao or 1688, the same search as ninjabuy.com. A pasted link answers that product.

querystringrequired: 2 to 120 characters, or a link.
providerstring?: taobao or 1688. taobao when left out.
pagenumber?: 0 to 20.

search_products answers

{
  "kind": "products",
  "products": [
    {
      "handle": "taobao-781204556120",
      "title": "Heavyweight cotton hoodie, washed",
      "price": { "amount": "45.00", "currency": "CNY" },
      "marketplace": "taobao",
      "url": "https://www.ninjabuy.com/products/taobao-781204556120"
    }
  ],
  "page": 0,
  "totalCount": 1840,
  "requestId": "5f7c2a1e-3b8d-4c61-9a0f-2e4d6b8c1a37",
  "warnings": []
}

`analyze_product`read-only

What one sale of each variant costs landed at the buyer's door, and the price that keeps your margin on your marketplace. Nothing is saved. Same figures as the import analysis.

linkstringrequired: A product link.
weight_gnumberrequired: Packed weight of one unit, in grams.
ship_tostring?: Two-letter country. US when left out.
lanestring?: saver or fast.
marketplacestring?: ebay, shopify, amazon or tiktok.
margin_percentnumber?: The margin to price for. 30 when left out.

analyze_product answers

{
  "title": "重磅水洗连帽卫衣",
  "shipTo": "US",
  "marketplace": "ebay",
  "brandHint": null,
  "variants": [
    {
      "sku": "5187209554",
      "label": "Black / M",
      "inStock": true,
      "procurement": "57.00",
      "parcel": "134.52",
      "landedUsd": "27.71",
      "suggestedPrice": "49.99",
      "marginPercent": "30.16"
    }
  ],
  "requestId": "5f7c2a1e-3b8d-4c61-9a0f-2e4d6b8c1a37",
  "warnings": []
}

`import_product`writes

Imports a listing with its analysis, as on the Imports API. Free. Answers the import to push or price again.

linkstringrequired: A product link or a finds sheet.
weight_gnumberrequired: Packed weight of one unit, in grams.
ship_tostring?: Two-letter country. US when left out.
lanestring?: saver or fast.
marketplacestring?: ebay, shopify, amazon or tiktok.
margin_percentnumber?: The margin to price for. 30 when left out.

import_product answers

{
  "import": {
    "id": "imp_2c9d",
    "status": "ready",
    "title": "重磅水洗连帽卫衣",
    "variants": 6,
    "inStock": 5
  },
  "requestId": "5f7c2a1e-3b8d-4c61-9a0f-2e4d6b8c1a37",
  "warnings": []
}

`push_to_shopify`writes

Saves an import as a product and lists it on your Shopify store as a draft, stocked at the Fulfilled by NinjaBuy location. Pushing again updates it. Same rules as Push to Shopify.

import_idstringrequired: From import_product.
variants{ sku, price }[]?: Which to keep and at what US$ price. In-stock ones at the suggested price when left out.
titlestring?: Your title.
shopstring?: Needed when several stores are linked.

push_to_shopify answers

{
  "product": "prd_8f2k",
  "shopify": {
    "status": "draft",
    "variants": 5,
    "adminUrl": "https://admin.shopify.com/store/acme-goods/products/8812042"
  },
  "skipped": [{ "sku": "5187209555", "reason": "sold_out" }],
  "requestId": "5f7c2a1e-3b8d-4c61-9a0f-2e4d6b8c1a37",
  "warnings": []
}

`list_synced_products`read-only

Your products with their last check, cost changes and stock, so you can see what moved.

statusstring?: active or paused.
changed_sincestring?: A date: only products whose cost or stock moved since.
cursorstring?: From the previous answer; leave out for the first page.
limitnumber?: 1 to 25. 25 when left out.

list_synced_products answers

{
  "products": [
    {
      "id": "prd_1x0a",
      "title": "Canvas Tote",
      "status": "active",
      "lastCheckedAt": "2026-11-04T02:10:00Z",
      "costChange": {
        "from": "¥42.00",
        "to": "¥48.00",
        "action": "repriced",
        "price": { "from": "$18.99", "to": "$20.99" }
      }
    }
  ],
  "cursor": null,
  "has_more": false,
  "requestId": "5f7c2a1e-3b8d-4c61-9a0f-2e4d6b8c1a37",
  "warnings": []
}

`set_sync_rule`writes

What to do when a seller raises a price: reprice to keep a margin, pause, or only tell you. For every product, or one. Same fields as Sync rules.

applies_tostringrequired: all, or a product id.
on_cost_increasestringrequired: reprice, pause or notify.
keep_margin_percentnumber?: With reprice.
max_increase_percentnumber?: With reprice: above it, pause.

set_sync_rule answers

{
  "rule": {
    "id": "rule_default",
    "appliesTo": "all",
    "onCostIncrease": {
      "action": "reprice",
      "keepMarginPercent": 40,
      "maxIncreasePercent": 15
    }
  },
  "requestId": "5f7c2a1e-3b8d-4c61-9a0f-2e4d6b8c1a37",
  "warnings": []
}

What to ask

Which of my orders are still waiting on a seller?

list_orders

Two: #1012 (the washed hoodie, bought Nov 1) and #1015 (two canvas totes). Both are paid and ordered from the seller; neither has reached the warehouse yet.

Is this hoodie worth selling on eBay? weidian.com/item.html?itemID=7750970856, about 180 g packed.

analyze_product

One sale to the US costs CN¥191.52 landed, about $27.71. At $49.99 eBay keeps about $7.20 and you keep $15.08, a 30% margin. Black / L is sold out. No brand words in the title.

Good. Put Black / M on my Shopify at $49.99, title “Heavyweight Washed Hoodie”.

import_productpush_to_shopify

Done: it is a draft on acme-goods.myshopify.com with 1 variant, stocked at Fulfilled by NinjaBuy. Check the photos, then publish it in Shopify.

Keep a 40% margin on everything, but never raise a price more than 15% at once.

set_sync_rule

Set for all products. A rise above 15% pauses the product instead, and I'll see it in list_synced_products.

Connect#

Claude

ChatGPT

Cursor

Claude Code and other command-line assistants

Sign-in and access#

Nothing here spends money#

Tools#

list_ordersread-only

orderread-only

warehouseread-only

productread-only

add_to_cartwrites

search_productsread-only

analyze_productread-only

import_productwrites

push_to_shopifywrites

list_synced_productsread-only

set_sync_rulewrites

What to ask#