# Hertwill MCP server for ecommerce AI agents

> Connect AI agents to products from European and US brands. Give Claude, Cursor and other MCP-compatible AI agents access to Hertwill's product catalog. Discover products, research brands, calculate margins and sync selected products to your ecommerce store.

Hertwill MCP is a local [Model Context Protocol](https://modelcontextprotocol.io) server. Your AI client starts it on your computer with npx. There is no hosted MCP endpoint.

```bash
npx @hertwill/mcp
```

- Web page: https://hertwill.com/mcp
- GitHub: https://github.com/Hertwill/hw-mcp
- npm: https://www.npmjs.com/package/@hertwill/mcp
- Hertwill API docs: https://hertwill.com/docs

## What you can do with Hertwill MCP

- **Discover products**: Search products from European and US brands by keyword, category, brand, price, stock and shipping region.
- **Research brands and niches**: Find brands and relevant products, compare options and look up each brand's shipping coverage and rates.
- **Calculate margins**: Evaluate products on wholesale price, shipping, stock and variants. Work out break-even and margin for your retail price. Wholesale prices need an API key.
- **Build your Import List** (API key required): Add, review and remove products in your Hertwill Import List.
- **Sync products to your store** (API key required): Sync products to your connected Shopify or WooCommerce store and check the status of sync jobs.

## Example prompts

- "Find children's products under €30 wholesale that ship to Germany."
- "Help me find products for a premium pet accessories store."
- "Find Montessori brands and compare their products and shipping options."
- "Calculate the potential margin for this product if I sell it for €89." (API key required)
- "Add these products to my Hertwill Import List." (API key required)
- "Sync the selected products to my Shopify store." (API key required)

## Connect Hertwill to your AI agent

Requires Node.js 20.11 or later.

### Claude Code

Run in your terminal:

```bash
claude mcp add --scope user hertwill -- npx @hertwill/mcp
```

--scope user makes Hertwill available in all your projects. Run /mcp inside Claude Code to check that it is connected.

### Claude Desktop

Add to claude_desktop_config.json: ~/Library/Application Support/Claude/ on macOS or %APPDATA%\Claude\ on Windows.

```json
{
  "mcpServers": {
    "hertwill": {
      "command": "npx",
      "args": ["@hertwill/mcp"]
    }
  }
}
```

Restart Claude Desktop after saving the file.

### Cursor

Add to .cursor/mcp.json in your project root:

```json
{
  "mcpServers": {
    "hertwill": {
      "command": "npx",
      "args": ["@hertwill/mcp"]
    }
  }
}
```

### VS Code + Copilot

Add to .vscode/mcp.json:

```json
{
  "servers": {
    "hertwill": {
      "type": "stdio",
      "command": "npx",
      "args": ["@hertwill/mcp"]
    }
  }
}
```

Cline, Continue and Windsurf follow the same pattern: add a server that runs `npx @hertwill/mcp`.

### API key

Product discovery works without an API key, but wholesale prices are hidden. Add a key to see wholesale prices and to use the Import List and sync tools. Create one at https://hertwill.com/account/api-keys (keys are scoped to one connected store).

For Claude Desktop and Cursor, use this config. In VS Code, add the same `env` block to the `hertwill` entry under `servers`.

```json
{
  "mcpServers": {
    "hertwill": {
      "command": "npx",
      "args": ["@hertwill/mcp"],
      "env": {
        "HERTWILL_API_KEY": "hw_live_your_api_key"
      }
    }
  }
}
```

For Claude Code (run `claude mcp remove hertwill` first if you already added it without a key):

```bash
claude mcp add --scope user hertwill -e HERTWILL_API_KEY=hw_live_your_api_key -- npx @hertwill/mcp
```

Replace the placeholder with your own key, and keep it out of config files you commit to shared repositories.

## Tools (13)

8 tools work without an API key and 5 need one. Authenticated tools only appear once `HERTWILL_API_KEY` is set.

- **Product search and browsing**: `search_products`, `list_products`
- **Product and brand details**: `get_product`, `get_brand`
- **Brand shipping information**: `get_brand_shipping_price_lists`
- **Product evaluation and margins**: `evaluate_product`, `calculate_margin`
- **Connection check**: `check_health`
- **Import List management** (API key required): `list_import_list`, `add_to_import_list`, `remove_from_import_list`
- **Product sync and sync-job status** (API key required): `sync_products`, `get_sync_jobs`

## Built-in prompts (8)

- `hw-niche-research`: Research a niche across categories and brands
- `hw-winner-scan`: Search, evaluate and calculate margins in one flow
- `hw-eu-winners`: Find EU-shippable products with margin analysis
- `hw-seasonal-picks`: Find products for a season
- `hw-competitor-match`: Find Hertwill alternatives to a competitor product
- `hw-margin-check` (API key required): Look at the margin of one product in detail
- `hw-import-batch` (API key required): Import products in bulk after you confirm the list
- `hw-store-health` (API key required): Check your API key, connection, Import List and sync jobs

Full list of tools, prompts and resources: https://github.com/Hertwill/hw-mcp

## Hertwill MCP or the Hertwill API?

- **Hertwill MCP**: For AI assistants and agents that discover and use Hertwill tools. https://github.com/Hertwill/hw-mcp
- **Hertwill API**: For developers building applications, integrations and backend workflows. https://hertwill.com/docs

## FAQ

### What is Hertwill MCP?

Hertwill MCP is an open-source [Model Context Protocol](https://modelcontextprotocol.io) server that gives AI agents access to Hertwill's catalog of products from European and US brands. It runs locally on your computer through npx and talks to the Hertwill API. There is no hosted endpoint to sign in to.

### What can AI agents do with Hertwill?

Agents can search and browse products, read product and brand details, check brand shipping rates, evaluate products and calculate margins. With an API key, they can also manage your Import List, sync products to your connected Shopify or WooCommerce store and check sync status.

### Which AI tools can use Hertwill MCP?

Any MCP client that can run a local (stdio) server. That includes Claude Code, Claude Desktop, Cursor, VS Code with GitHub Copilot, Cline, Continue and Windsurf.

### Do I need a Hertwill account or API key?

Not to get started. The 8 discovery tools work without an account or API key, but wholesale prices are hidden. Add an API key to see wholesale prices and to use the Import List and sync tools. API keys are created per store in [your account](https://hertwill.com/account/api-keys), so you need a Hertwill account with a connected store.

### Is Hertwill MCP free to use?

Yes. The MCP server is open source under the MIT license and product discovery is free. Adding and selling products follows your Hertwill plan: the free plan covers up to 5 products and paid plans raise the limits. See [pricing](https://hertwill.com/pricing).

### Can Hertwill MCP sync products to Shopify and WooCommerce?

Yes. With an API key, your agent can add products to your Import List, sync them to the Shopify or WooCommerce store connected to that key and check the status of each sync job.

### Can AI agents place orders through Hertwill MCP?

No. The MCP has no ordering or fulfillment tools. When a customer buys a synced product in your store, Hertwill fulfills the order through your store integration, just like any other Hertwill product.

### What's the difference between Hertwill MCP and the Hertwill API?

Hertwill MCP is for AI assistants and agents. It wraps the API in tools and prompts that an agent can discover and call. The [Hertwill API](https://hertwill.com/docs) is for developers building applications, integrations and backend workflows that call the endpoints directly.