hertwill-mcp

An MCP server for the Hertwill dropshipping API (API docs). Use it to search the catalog, manage your store's import list, and publish products to your Shopify or WooCommerce store, all from Claude or any other MCP client.

• Built on the MCP TypeScript SDK v2 (@modelcontextprotocol/server). It serves the 2026-07-28 protocol revision and still works with clients on the 2025 revisions.

• Uses the stdio transport. It needs Node.js 20 or newer.

Tools

¹ Catalog tools work without a key, but wholesale price comes back null unless a key is set.

The API's account endpoints (/v1/auth/* and /v1/api-keys) are deliberately left out. They need your email and password, and you manage them in the Hertwill dashboard.

Related MCP server: xurprise MCP

Setup

1. Create a store-scoped API key (hw_live_…) in your Hertwill account dashboard.

2. Add the server to your MCP client.

Claude Code

claude mcp add -s user hertwill -e HERTWILL_API_KEY=hw_live_xxx -- npx -y github:aanndryyyy/hertwill-mcp

Claude Desktop, Cursor, and other clients using mcpServers JSON

{
  "mcpServers": {
    "hertwill": {
      "command": "npx",
      "args": ["-y", "github:aanndryyyy/hertwill-mcp"],
      "env": { "HERTWILL_API_KEY": "hw_live_xxx" }
    }
  }
}

From a local clone

git clone https://github.com/aanndryyyy/hertwill-mcp.git
cd hertwill-mcp && npm install   # builds dist/ automatically
claude mcp add -s user hertwill -e HERTWILL_API_KEY=hw_live_xxx -- node "$PWD/dist/index.js"

Environment variables

Example prompts

• "Find alpaca throws under €150 that ship to Finland."

• "Add products 11167 and 9292 to my import list."

• "Sync product 11167 to my store at €219."

• "Is anything failing to sync in my store?"

Notes

• Selling price is absolute. sync_product takes the retail price in your store's currency (e.g. 24.99), not a markup multiplier. The API rejects prices below wholesale with PRICE_BELOW_COST.

• Variants. sync_product first adds the product to the import list (a no-op if it's already there), so it gets the authoritative (id, dropship_id) pairs. Every variant then gets selling_price, unless you override individual variants with variation_prices.

• Confirmation before writes. If your client supports elicitation, sync_product and remove_from_import_list ask you to confirm first. For a sync, the prompt shows the product, your selling price and the wholesale cost. If you decline, nothing is synced or removed, and the tool returns status: "declined" (or "cancelled" if you dismissed the prompt). A declined sync still leaves the product in your import list, because sync_product stages it there before asking. The confirmation is bound to the exact arguments through a signed requestState, so a client cannot answer it in advance or reuse it for other arguments. Clients without form elicitation skip this step and rely on their own tool-approval prompt.

• Structured output. Every tool declares an outputSchema and returns structuredContent, with the same JSON as text. List tools return objects: { categories }, { brands }, { price_lists }, { results }.

• Rate limits. The API allows 60 requests/min per IP on public endpoints and 300/min per key on authenticated ones. A 429 comes back as a tool error that includes the retry delay.

• Response size. List responses leave out HTML descriptions and facets by default. Pass include_description / include_facets to get them.

Development

npm install
npm run build
npx @modelcontextprotocol/inspector node dist/index.js   # interactive testing

# End-to-end smoke test against the live API. It's read-only; authenticated tools run only when a key is set.
HERTWILL_API_KEY=hw_live_xxx npm test                  # 2026-07-28 protocol
PROTOCOL=legacy HERTWILL_API_KEY=hw_live_xxx npm test  # 2025-era protocol

License

MIT