# Heartland Retail MCP by usefulapi

> Heartland Retail MCP by usefulapi is an MCP server. Read items, stock, customers and sales orders; create and update customers in Heartland Retail. It runs as a hosted remote server, so there is nothing to install locally.

- **Kind:** MCP server
- **Website:** https://usefulapi.io/heartland-retail/
- **Repository:** https://github.com/m190/usefulapi-mcp/tree/HEAD/servers/heartland-retail
- **MCP Registry name:** io.usefulapi/heartland-retail
- **Listing updated:** 2026-11-13

## About

Read items, stock, customers and sales orders; create and update customers in Heartland Retail.

## Install

### Claude Code (Terminal)

```sh
claude mcp add --transport http heartland-retail https://heartland-retail.usefulapi.io/mcp
```

### Claude Desktop (Settings → Connectors → Add custom connector)

```sh
https://heartland-retail.usefulapi.io/mcp
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "heartland-retail": {
      "url": "https://heartland-retail.usefulapi.io/mcp"
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "heartland-retail": {
      "type": "http",
      "url": "https://heartland-retail.usefulapi.io/mcp"
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "heartland-retail": {
      "serverUrl": "https://heartland-retail.usefulapi.io/mcp"
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "heartland-retail": {
      "type": "http",
      "url": "https://heartland-retail.usefulapi.io/mcp"
    }
  }
}
```

## Tools

- `heartlandretail_whoami`: Show the Heartland Retail user behind the API token, and confirm the token works. Use it first when a call returns 401 or 403. Heartland Retail: GET /api/system/whoami.
- `heartlandretail_list_items`: Search the store's items (products) by text or JSON filter, with cost, price and vendor ids. Heartland Retail: GET /api/items.
- `heartlandretail_get_item`: Get one item by id: cost, price, financial class and primary vendor. Heartland Retail: GET /api/items/{item_id}.
- `heartlandretail_list_inventory_values`: Show stock quantities and values, optionally grouped (for example by item_id or location_id) and filtered to one item. Heartland Retail: GET /api/inventory/values.
- `heartlandretail_list_locations`: List the store's locations (stores, warehouses) with their ids. Heartland Retail: GET /api/locations.
- `heartlandretail_list_customers`: Search customers by name, email or a JSON filter. Heartland Retail: GET /api/customers.
- `heartlandretail_get_customer`: Get one customer by id: name, email, default address ids, custom fields and loyalty points. Heartland Retail: GET /api/customers/{customer_id}.
- `heartlandretail_create_customer`: Create a customer. Give a first name or a last name (or both). Returns the new customer id. Heartland Retail: POST /api/customers.
- `heartlandretail_update_customer`: Change the name or email of one customer. Only the fields you give change. Heartland Retail: PUT /api/customers/{customer_id}.
- `heartlandretail_list_sales_orders`: Search sales orders by text or JSON filter (for example a status). Shows customer, status, shipping and totals. Heartland Retail: GET /api/sales/orders.
- `heartlandretail_get_sales_order`: Get one sales order by id. Heartland Retail: GET /api/sales/orders/{order_id}.
- `heartlandretail_list_sales_order_lines`: List the lines (items, quantities, prices) of one sales order. Heartland Retail: GET /api/sales/orders/{order_id}/lines.
- `heartlandretail_list_sales_invoices`: Search sales invoices by text or JSON filter. Heartland Retail: GET /api/sales/invoices.
- `heartlandretail_list_sales_tickets`: Search point-of-sale tickets (till sales) by text or JSON filter. Heartland Retail: GET /api/sales/tickets.
- `heartlandretail_list_vendors`: Search purchasing vendors (suppliers) by text or JSON filter. Heartland Retail: GET /api/purchasing/vendors.
- `heartlandretail_get_gift_card`: Get one gift card by its card number: value and status. Heartland Retail: GET /api/gift_cards/{gift_card_number}.

## FAQ

### How do I add Heartland Retail MCP by usefulapi to Claude Code?

Run this command in your terminal: claude mcp add --transport http heartland-retail https://heartland-retail.usefulapi.io/mcp

---
Source: https://ai-powered.com/mcp/heartland-retail-mcp-by-usefulapi
