hertwill-mcp
The hertwill-mcp server wraps the Hertwill dropshipping API, enabling AI agents to discover products, evaluate margins, manage import lists, and sync products to Shopify/WooCommerce through natural language.
Product Discovery & Evaluation (no API key required)
search_products— Hybrid keyword + semantic search with filters (category, brand, price, stock, EU shipping)list_products— Filter-driven catalog browsing without a search queryget_product— Full product details including variants and shipping countriesget_brand/get_brand_shipping_price_lists— Brand assets and shipping price listsevaluate_product— Structured viability scorecard covering margin inputs, shipping, stock, and variant spreadcalculate_margin— Pure-math break-even and margin calculator (no network call)check_health— Server version, API reachability, and rate-limit budget
Import List & Sync (API key required)
list_import_list— View staged products with filtering and paginationadd_to_import_list/remove_from_import_list— Batch-stage or remove up to 50 products by IDsync_products— Trigger a Shopify/WooCommerce sync with a specified markup multiplierget_sync_jobs— Check sync job status (queued, syncing, synced, failed)
Pre-built Prompts
8 structured workflow prompts including hw-winner-scan, hw-niche-research, hw-eu-winners, hw-seasonal-picks, hw-competitor-match, hw-margin-check, hw-import-batch, and hw-store-health.
Context Resources 5 readable resources: categories taxonomy, brands taxonomy, product JSON schema, rate limits guide, and EU shipping guide.
Allows triggering product syncs to a Shopify store and checking the status of sync jobs.
Allows triggering product syncs to a WooCommerce store and checking the status of sync jobs.
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., "@hertwill-mcp Find trending pet supplies with at least 60% margin"
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.
@hertwill/mcp
A Model Context Protocol server that wraps the Hertwill dropshipping API — letting any MCP-capable AI agent discover products, evaluate margins, manage an import list, and trigger syncs to Shopify/WooCommerce through natural language.
npx @hertwill/mcpQuick Start
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"hertwill": {
"command": "npx",
"args": ["@hertwill/mcp"],
"env": {
"HERTWILL_API_KEY": "your-api-key-here"
}
}
}
}Cursor
Add to .cursor/mcp.json in your project root:
{
"mcpServers": {
"hertwill": {
"command": "npx",
"args": ["@hertwill/mcp"],
"env": {
"HERTWILL_API_KEY": "your-api-key-here"
}
}
}
}VS Code + Copilot
Add to .vscode/mcp.json:
{
"servers": {
"hertwill": {
"type": "stdio",
"command": "npx",
"args": ["@hertwill/mcp"],
"env": {
"HERTWILL_API_KEY": "your-api-key-here"
}
}
}
}Cline / Continue / Windsurf
Each follows the same pattern — add an MCP server entry pointing to npx @hertwill/mcp with the HERTWILL_API_KEY env var. Refer to your client's MCP configuration docs.
No API key? The server starts without one. All 8 discovery tools work immediately — you only need a key for import list and sync operations. Get one at hertwill.com.
Related MCP server: WooCommerce MCP Server
What You Can Ask
Once connected, talk to your AI agent naturally:
"Find me winning EU-shippable kitchen gadgets under €25"
"Evaluate product 4827 — is the margin viable for Facebook ads?"
"Show me trending pet supplies with at least 60% margin potential"
"Add products 1001, 1002, 1003 to my import list"
"What's the health of my store connection?"
Tools (13)
Discovery (no API key required)
Tool | Purpose |
| Hybrid keyword + semantic search with filters (category, brand, price, stock, EU shipping) |
| Browse and filter catalog without a search query |
| Full product detail — variants, shipping regions, descriptions |
| Brand detail incl. marketing material links (logo, cover, downloadable assets) |
| A brand's shipping price lists (coverage tags + per origin→destination rates) |
| Factual viability scorecard: margin inputs, shipping, stock, variant spread |
| Pure-math break-even and margin calculator (no network call) |
| Server version, API reachability, rate limit bucket state |
Import & Sync (API key required)
Tool | Purpose |
| View products in your import list |
| Add products by ID to your import list |
| Remove a product from your import list |
| Check Shopify/WooCommerce sync job status |
| Trigger a product sync to your connected store |
Prompts (8)
Pre-built workflows the agent can invoke as structured starting points:
Prompt | Purpose |
| Search, evaluate, and calculate margin in one flow |
| Deep-dive a niche with category + brand analysis |
| Find EU-shippable winners with margin analysis |
| Discover products for a specific season |
| Find Hertwill alternatives to a competitor product |
| Single-product margin deep dive |
| Bulk import with mandatory user confirmation |
| Full store diagnostic: auth, API, import list, sync jobs |
Resources (5)
Static and dynamic context the agent can read:
Resource | URI |
Categories taxonomy |
|
Brands taxonomy |
|
Product JSON Schema |
|
Rate limits guide |
|
EU shipping guide |
|
Configuration
Environment Variable | Required | Default | Description |
| No | — | Hertwill API key ( |
| No |
| Log level: |
| No |
| Set to |
Troubleshooting
"Parse error" or garbled output from the MCP client
Cause: Something is writing to stdout besides JSON-RPC frames. Common culprits: an npm lifecycle script printing a banner, or a stray console.log in a dependency.
Fix: Ensure you're using npx @hertwill/mcp directly (not wrapping it in a shell script that echoes). Logs go to stderr, never stdout.
"Unauthorized" or "Invalid API key format"
Cause: The HERTWILL_API_KEY env var is missing, empty, or doesn't match the hw_live_... / hw_test_... format.
Fix: Check the key is set in your MCP client config (not your shell profile — MCP servers don't inherit your shell environment). Get a key at hertwill.com.
"Rate limit exceeded. Retry after Xs."
Cause: You've hit the Hertwill API rate limit (60 req/min public, 300 req/min authenticated).
Fix: The server handles backoff automatically. Wait for the indicated retry period. If you're hitting limits frequently, batch your requests — use hw-import-batch instead of individual add_to_import_list calls.
Development
# Install dependencies
pnpm install
# Run in development
pnpm tsx src/index.ts
# Run tests (436 tests)
pnpm test
# Build
pnpm build
# Full validation (build + lint + security gates + tests)
pnpm validateSecurity Gates
The validate script includes four security gates that run in CI:
check:key-reads —
process.env.HERTWILL_API_KEYaccessed only insrc/config.tscheck:key-leakage — no full-length API key values in the source tree
check:boundaries — import boundary enforcement between layers
audit —
pnpm audit --audit-level=highpasses with zero high-severity CVEs
Tech Stack
Runtime: Node.js >= 20.11, ESM-only
MCP SDK:
@modelcontextprotocol/sdk^1.29Validation: Zod v4
HTTP: Native
fetch+openapi-fetch(typed, 6 KB)Rate limiting: Bottleneck (60/min public, 300/min authenticated)
Retry: p-retry with exponential backoff + jitter
Logging: Pino to stderr (stdout reserved for JSON-RPC)
Build: tsup (ESM bundle with shebang)
Testing: Vitest + MSW + in-process MCP client
License
MIT
Available Tools
11 toolsadd_to_import_listA
Stage 1-50 Hertwill products into the authenticated store's import list in a single batch. Pass up to 50 product IDs in a single call. Do NOT call this tool in a loop for individual products. Do NOT use before the user has chosen products (use search_products or list_products) or to push staged products to the store (use sync_products). Returns {added, skipped, import_list_size}. Requires HERTWILL_API_KEY.
Inputs: product_ids (required).
calculate_marginA
Pure math utility: given cost, retail, ad spend, and VAT rate, return margin amount, margin %, and break-even ad-spend band. Makes zero API calls. Do NOT use when the user wants a real product evaluation (use evaluate_product) or to find products (use search_products). No auth required.
Inputs: cost (required), retail_price (required), ad_spend, vat_rate.
check_healthA
Report server version, Hertwill API reachability, and remaining rate-limit budget for both the public (60/min) and authenticated (300/min) buckets. Use for connectivity and capacity diagnostics. Do NOT use to search products (use search_products). No auth required.
Inputs: no named parameters.
evaluate_productA
Produce a factual structured viability scorecard for one product — margin inputs, shipping coverage, variant spread, and stock signal. Use when the user wants a comparable decision summary. Do NOT use when the user only wants product details (use get_product), pure margin math (use calculate_margin), or to find candidates first (use search_products). No auth required.
Inputs: product_id (required), target_retail_price, ad_spend_per_unit, vat_rate.
get_productA
Return full detail for a single Hertwill product by ID, including variations and shipping coverage (ships_to as ISO country codes). Use when you already have a product ID and need variants or shipping detail. Do NOT use to search (use search_products), browse (use list_products), or score viability (use evaluate_product). Supplier text is wrapped in <untrusted_supplier_content>. No auth required.
Inputs: product_id (required).
get_sync_jobsA
Return paginated sync job status for the authenticated store. Use to poll or review previously triggered syncs. Do NOT use to trigger a new sync (use sync_products) or to inspect the import list (use list_import_list). Returns a paginated envelope of {sync_job_id, product_id, status, created_at, finished_at, error}. Requires HERTWILL_API_KEY.
Inputs: page, per_page, status.
list_import_listA
Return the authenticated store's current Hertwill import list, paginated. Use to audit what's staged for sync. Do NOT use to search the catalog (use search_products), stage new products (use add_to_import_list), or check sync status (use get_sync_jobs). Returns a paginated envelope; ships_to is not in list items — use get_product for shipping. Requires HERTWILL_API_KEY.
Inputs: page, per_page, status, order_by, +1 more.
list_productsA
Browse and filter the Hertwill catalog without a search query (category, brand, price range, stock status, shipping region). Use for filter-driven enumeration. Do NOT use when the request has keywords or natural-language intent (use search_products), or when the user wants one product's detail (use get_product). Returns a paginated envelope with structured prices and bucketed stock; ships_to is absent from list items — use get_product for shipping. No auth required.
Inputs: page, per_page, min_price, max_price, +7 more.
remove_from_import_listA
Remove 1-50 products from the authenticated store's import list in a single batch call. Pass IDs in one call rather than looping. Do NOT use to view the current list (use list_import_list) or to add items (use add_to_import_list). Returns {removed, skipped, import_list_size}. Requires HERTWILL_API_KEY.
Inputs: product_ids (required).
search_productsA
Hybrid keyword + semantic search over the Hertwill catalog. Use when the user expresses intent with words or a natural-language query. Do NOT use for filter-only browsing (use list_products) or single-product detail (use get_product). Returns a paginated envelope with items carrying structured price {amount, currency} and bucketed stock; ships_to is not in list items — call get_product for shipping detail. Supplier text is wrapped in <untrusted_supplier_content>. No auth required.
Inputs: query (required), page, per_page, min_price, +8 more.
sync_productsA
Trigger a Shopify or WooCommerce sync for one product already staged in the import list, with a specified markup. Use to push a single staged product to the connected store. Do NOT use to check sync progress (use get_sync_jobs); if the product isn't yet staged, call add_to_import_list first. Returns {sync_job_id, product_id, status: "queued", markup_applied}. Requires HERTWILL_API_KEY.
Inputs: product_id (required), default_store_markup (required), currency, lang.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Each tool has a clearly defined purpose that does not overlap significantly with others. For example, search_products and list_products are differentiated by query type, and evaluate_product versus calculate_margin serve distinct evaluation needs. No two tools appear to do the same thing.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., add_to_import_list, get_product, search_products). There is no mixing of styles, making the naming predictable and easy to understand.
With 11 tools covering catalog search, import list management, syncing, evaluation, and health checks, the tool count is well-scoped for a product management MCP. Each tool serves a distinct and necessary function without bloat.
The tool set covers the full intended workflow: discovering products (list_products, search_products), retrieving details (get_product), evaluating viability (evaluate_product, calculate_margin), managing the import list (add, list, remove), triggering sync (sync_products), monitoring sync jobs (get_sync_jobs), and checking system health (check_health). There are no obvious gaps for the domain.
Maintenance
Related MCP Connectors
Print-on-demand catalog, listings, and fulfillment for AI agents.
Let your AI manage WooCommerce and Shopify stores: products, SEO, descriptions and images.
Launch and manage online stores with AI agents: products, inventory, pricing, orders and promotions.
Product search for AI agents: Amazon + Shopify, cart-to-checkout buy path. Pay-per-call, no API key.
Related MCP Servers
- AlicenseAqualityDmaintenanceConnects Printful's print-on-demand API to AI assistants like Claude and Cursor to automate business operations. It enables users to browse catalogs, manage orders, generate mockups, and calculate shipping rates through natural language.1937MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to manage WooCommerce stores, including products, orders, customers, categories, coupons, attributes, variations, order notes, refunds, reports, payment gateways, meta data, reviews, settings, data, posts, and system status through natural language.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to interact with WooCommerce stores via the WooCommerce REST API, supporting operations like listing products, orders, and customers.308 npmMIT
- AlicenseAqualityDmaintenanceEnables AI agents to search products, lookup barcodes, and manage shopping carts and wishlists using free e-commerce APIs.8MIT