@marketbasketanalysis/mcp

An MCP server that gives any AI agent access to real co-purchase intelligence and merchant ops tooling from an ecommerce merchant's order history. 19 tools across discovery, bundle, insight, replenishment, merchant ops, and advanced mining. Works with Claude Desktop, Claude Code, Cursor, Windsurf, Cline, the OpenAI Agent SDK, and any other host that speaks the MCP stdio protocol. Works for merchants on Shopify, BigCommerce, WooCommerce, Magento, and OroCommerce. See "Platform coverage" below for which tools reach the self-hosted backends.

One npm package serves every marketplace. The server is platform agnostic, it is an HTTP client that calls a store's MBA backend over the public REST API. You re-point the whole server at any store with a single switch (MBA_API_BASE, see below). Most tools work on all five platforms; a handful depend on a backend route that not every platform ships yet. Per-tool marketplace coverage is the Tool catalog "Marketplace" column.

Why this exists

When a customer asks an AI shopping agent "what goes with the gym backpack?" the agent should give a real answer based on the merchant's actual order data, not a generic "you might also like" guess. When a merchant asks Claude "what should I work on this week?" the agent should pull from a ranked weekly plan, not invent tasks. This server makes both of those flows available to any MCP host in one line of config.

5-line install (Claude Desktop)

{
  "mcpServers": {
    "marketbasketanalysis": {
      "command": "npx",
      "args": ["-y", "@marketbasketanalysis/mcp"],
      "env": { "MBA_API_KEY": "mba_live_YOUR_KEY_HERE" }
    }
  }
}

Paste into ~/Library/Application Support/Claude/claude_desktop_config.json (macOS), restart Claude Desktop, the marketbasketanalysis server appears in the tools list with all 19 tools.

Zero-install: the hosted endpoint

The same server runs hosted at https://mcp.marketbasketanalysis.com/mcp (MCP streamable HTTP). Nothing to install; send your key as a bearer header instead of an env var:

claude mcp add --transport http marketbasketanalysis \
  https://mcp.marketbasketanalysis.com/mcp \
  --header "Authorization: Bearer mba_live_YOUR_KEY_HERE"

Works with any remote-capable MCP client (Claude Code, Cursor, Smithery, custom agents). Optional headers: X-MBA-Base re-points at another MBA-operated plane (for example https://bigcommerce.marketbasketanalysis.com); X-MBA-Platform mirrors the MBA_PLATFORM env var. Self-hosted WooCommerce and Magento stores are not reachable from the hosted endpoint by design, use the npx install above with MBA_API_BASE pointed at your own site.

Point the server at your store (MBA_API_BASE)

The base URL is per-store configuration. By default the server talks to the shared hosted backend at https://app.marketbasketanalysis.com. If your data lives anywhere else, a BigCommerce store, a self-hosted backend, or a staging instance, set MBA_API_BASE so every tool reaches your own data plane:

{
  "mcpServers": {
    "marketbasketanalysis": {
      "command": "npx",
      "args": ["-y", "@marketbasketanalysis/mcp"],
      "env": {
        "MBA_API_KEY": "mba_live_YOUR_KEY_HERE",
        "MBA_API_BASE": "https://your-store-backend.example.com"
      }
    }
  }
}

MBA_API_BASE is the single switch that re-points the whole server; all 19 tools route through it. The value must be an https:// URL for non-local hosts (loopback, private, link-local, and metadata-service hosts are refused). For local development against a backend on localhost, set ALLOW_LOCAL_API_BASE=1 to allow an http://localhost base. Env-var changes take effect at server startup, so restart your MCP host after editing the value.

MBA_API_BASE per platform

The base URL is per-store configuration. Shopify, BigCommerce, and OroCommerce stores are served by the shared hosted backend, so they use the default. WooCommerce and Magento run the backend locally inside the store install, so point the server at the store's own domain:

Platform coverage

The server writes canonical /api/v1/... paths and rewrites them per platform, because WooCommerce and Magento run the backend inside the store on their own REST conventions (marketbasketanalysis/v1 and V1/marketbasketanalysis respectively).

10 of the 19 tools reach WooCommerce and Magento: the six that derive from /recommendations (get_recommendations, get_bundle_for_cart, score_cross_sell, analyze_basket, propose_subscription_bundle, score_return_risk), plus find_substitutes, get_rationale, forecast_bundle, and predict_reorder.

The other 9 are the merchant-ops surface: get_opportunities, triage_opportunity, get_weekly_plan, execute_weekly_plan_action, get_drift_alerts, get_forecast_alerts, explain_opportunity, explain_drift, and mine_hui_itemsets. Those endpoints do not exist on the self-hosted backends. Calling one there returns a clear "not available on this platform" error naming the endpoint, with no network round trip, rather than an opaque 404.

For step-by-step install (config file location per OS, where to mint an API key, troubleshooting):

• Claude Desktop: dist/mcp/claude-desktop-setup.md
• Cursor: dist/mcp/cursor-setup.md
• Windsurf: dist/mcp/windsurf-setup.md

Authentication

The server reads MBA_API_KEY from the environment your MCP host passes in and sends it as a Bearer token on every request. To get a key:

1. Open the MarketBasketAnalysis admin (Shopify app drawer, or BigCommerce / WooCommerce / Magento / OroCommerce admin).
2. Click "API keys" in the left nav.
3. Click "Create key", name it, and copy the mba_live_ value (it is shown once).

Keys are per-shop, revocable, and rotated from the same screen. Only the SHA-256 hash is stored, so re-mint if a key leaks.

Auth model differs per marketplace, the MCP server abstracts it, but worth knowing:

• Shopify, BigCommerce: Bearer mba_live_... straight through. This is the common path.
• WooCommerce: Bearer against a Woo-minted key, which must carry the customer_data scope for predict_reorder.
• Magento: tools reach the store over the Magento REST surface (/V1/marketbasketanalysis/* and /V1/mba/*); some routes are admin-token / ACL scoped on the store side.
• OroCommerce: the store sits behind the platform OAuth2 firewall for /api/ routes; the hosted backend the thin client proxies to is what the MCP server actually calls, so the mba_live_ key still applies.

Tool catalog

19 tools, organized into the four Basket AI agent roles plus two operational groups. The Marketplace column states which backends ship the route the tool calls, which is not the same as which backends this server can currently REACH: see "Platform coverage" above. "All five" means Shopify, BigCommerce, WooCommerce, Magento, OroCommerce.

Discovery

Bundle

These derive everything from /recommendations (the server composes the bundle/scoring logic client-side), so they need no extra backend route and work everywhere.

Insight

Also /recommendations-derived, so universal.

Replenishment + forecasting

Merchant ops