@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/mcp

Quick 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.

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
`search_products`	Hybrid keyword + semantic search with filters (category, brand, price, stock, EU shipping)
`list_products`	Browse and filter catalog without a search query
`get_product`	Full product detail — variants, shipping regions, descriptions
`get_brand`	Brand detail incl. marketing material links (logo, cover, downloadable assets)
`get_brand_shipping_price_lists`	A brand's shipping price lists (coverage tags + per origin→destination rates)
`evaluate_product`	Factual viability scorecard: margin inputs, shipping, stock, variant spread
`calculate_margin`	Pure-math break-even and margin calculator (no network call)
`check_health`	Server version, API reachability, rate limit bucket state

Import & Sync (API key required)

Tool	Purpose
`list_import_list`	View products in your import list
`add_to_import_list`	Add products by ID to your import list
`remove_from_import_list`	Remove a product from your import list
`get_sync_jobs`	Check Shopify/WooCommerce sync job status
`sync_products`	Trigger a product sync to your connected store

Prompts (8)

Pre-built workflows the agent can invoke as structured starting points:

Prompt	Purpose
`hw-winner-scan`	Search, evaluate, and calculate margin in one flow
`hw-niche-research`	Deep-dive a niche with category + brand analysis
`hw-eu-winners`	Find EU-shippable winners with margin analysis
`hw-seasonal-picks`	Discover products for a specific season
`hw-competitor-match`	Find Hertwill alternatives to a competitor product
`hw-margin-check`	Single-product margin deep dive
`hw-import-batch`	Bulk import with mandatory user confirmation
`hw-store-health`	Full store diagnostic: auth, API, import list, sync jobs

Resources (5)

Static and dynamic context the agent can read:

Resource	URI
Categories taxonomy	`hertwill://taxonomy/categories`
Brands taxonomy	`hertwill://taxonomy/brands`
Product JSON Schema	`hertwill://schemas/product`
Rate limits guide	`hertwill://docs/rate-limits`
EU shipping guide	`hertwill://docs/eu-shipping`

Configuration

Environment Variable	Required	Default	Description
`HERTWILL_API_KEY`	No	—	Hertwill API key (`hw_live_...`). Enables import list and sync tools.
`HERTWILL_MCP_LOG_LEVEL`	No	`info`	Log level: `fatal`, `error`, `warn`, `info`, `debug`, `trace`
`HERTWILL_MCP_TELEMETRY`	No	`false`	Set to `true` to enable opt-in telemetry (no PII collected)

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 validate

Security Gates

The validate script includes four security gates that run in CI:

check:key-reads — process.env.HERTWILL_API_KEY accessed only in src/config.ts
check:key-leakage — no full-length API key values in the source tree
check:boundaries — import boundary enforcement between layers
audit — pnpm audit --audit-level=high passes with zero high-severity CVEs

Tech Stack

Runtime: Node.js >= 20.11, ESM-only
MCP SDK: @modelcontextprotocol/sdk ^1.29
Validation: 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