listbee-mcp

MCP server for ListBee — commerce API for AI agents. 20 tools.

---

Connect

Remote (zero install): https://mcp.listbee.so — for ChatGPT Apps, Claude API Connector, remote agents. Each request needs Authorization: Bearer lb_... header.

Local (stdio): npx -y listbee-mcp — for Claude Desktop, Cursor, VS Code, Cline.

---

Golden Path

Three calls to go from zero to a live, selling product page:

create_listing    →  get_listing  →  publish_listing
  name, price        check status     go live

1. Create — set deliverable for managed auto-delivery, or agent_callback_url for async agent fulfillment

{
  "name": "50 Cold Outreach Templates",
  "price": 1900,
  "deliverable": { "type": "url", "value": "https://cdn.example.com/templates.zip" }
}

2. Inspect readiness — get_listing tells you what's missing and how to fix it

3. Publish — publish_listing makes the product page live

---

Bootstrap (no API key)

Don't have a ListBee account yet? Start the MCP server without a key — it exposes bootstrap tools for account creation:

bootstrap_start  →  bootstrap_verify
  send OTP email     verify 6-digit → get API key + Stripe onboarding URL

npx -y listbee-mcp   # no --api-key needed

bootstrap_verify returns { account_id, api_key, stripe_onboarding_url }. Store the key immediately, then restart the MCP session with --api-key lb_... to unlock all tools.

After restarting with the key, call bootstrap_poll to check whether Stripe Connect onboarding is complete before creating listings.

For the HTTP transport, sessions initialized without a Bearer header are automatically bootstrap-only. After bootstrap, open a new session with the key to access the full tool set.

---

Install

Requires Node.js 20+.

Claude Desktop

~/.claude/claude_desktop_config.json

{
  "mcpServers": {
    "listbee": {
      "command": "npx",
      "args": ["-y", "listbee-mcp", "--api-key", "lb_..."]
    }
  }
}

Or with an env var:

{
  "mcpServers": {
    "listbee": {
      "command": "npx",
      "args": ["-y", "listbee-mcp"],
      "env": {
        "LISTBEE_API_KEY": "lb_..."
      }
    }
  }
}

Cursor

.cursor/mcp.json

{
  "mcpServers": {
    "listbee": {
      "command": "npx",
      "args": ["-y", "listbee-mcp", "--api-key", "lb_..."]
    }
  }
}

Claude Code

claude mcp add listbee -- npx -y listbee-mcp --api-key lb_...

CLI

npx -y listbee-mcp --api-key lb_...

---

Remote / HTTP Transport

For hosted deployments (ChatGPT Apps, Claude API Connector, remote agents):

npx -y listbee-mcp --transport http --port 3000

Each connecting agent provides their API key via Authorization: Bearer header.

Docker

docker build -t listbee-mcp .
docker run -p 8080:8080 listbee-mcp

Health Checks

• GET /health — basic liveness
• GET /ready — confirms tools are loaded

---

Options

Flag	Env var	Default	Description
--api-key <key>	LISTBEE_API_KEY	—	ListBee API key. Optional — omit to start in bootstrap-only mode.
--base-url <url>	LISTBEE_BASE_URL	https://api.listbee.so	API base URL
--transport <stdio|http>	—	stdio	Transport mode
--port <number>	PORT	8080	HTTP port (http mode only)
--tools <list>	—	all tools	Comma-separated list of tools to load
--help, -h	—	—	Show help

Selective tool loading — load only what you need:

npx -y listbee-mcp --api-key lb_... --tools create_listing,get_listing,publish_listing

---

Tools

Bootstrap (no API key required for start + verify)

Tool	Description
bootstrap_start	Send a one-time passcode to an email address. Step 1 of 2 for account creation.
bootstrap_verify	Verify the OTP from email. Issues the API key and Stripe onboarding URL. Step 2 of 2. Store the key immediately.
bootstrap_poll	Poll Stripe Connect onboarding readiness. Returns ready=true once charges are enabled. Requires API key.

Account

Tool	Description
get_account	Get the account's full state including readiness and billing status.
update_account	Update account-level settings (display name, bio, avatar, GA tracking, events callback URL).
delete_account	Permanently delete the account and all data. Irreversible.

Listings

Tool	Description
create_listing	Create a new listing for sale. Set deliverable for managed delivery or agent_callback_url for async agent fulfillment. Returns checkout URL and readiness.
get_listing	Get full listing state including readiness. Call after every change.
update_listing	Update title, price, deliverable, or other listing details.
list_listings	List all listings for the current account.
publish_listing	Publish a listing so buyers can access the product page.
delete_listing	Permanently delete a listing.

Orders

Tool	Description
list_orders	See all sales and order status.
get_order	Get full order details including buyer info, payment, and unlock URL.
fulfill_order	Push a deliverable to a buyer or mark as fulfilled (external fulfillment). Accepts optional metadata.
refund_order	Issue a full refund for an order through Stripe.
order_redeliver	Re-queue order.paid / order.fulfilled to the listing's agent_callback_url. Rate-limited: 10/hour/order.

Stripe

Tool	Description
start_stripe_connect	Start Stripe Connect onboarding. Returns a URL — the human must open it in a browser.
disconnect_stripe	Disconnect the Stripe account from ListBee.

API Keys

Tool	Description
api_key_self_revoke	Self-revoke the API key used to authenticate this call. Idempotent. Use when credential is compromised.

---

Readiness

Every listing response includes a readiness object that tells you exactly what's needed before the listing can go live — and how to fix it.

{
  "readiness": {
    "sellable": false,
    "publishable": false,
    "actions": [
      {
        "code": "connect_stripe",
        "kind": "human",
        "message": "Connect a Stripe account to accept payments.",
        "resolve": {
          "method": "POST",
          "endpoint": "/v1/account/stripe/connect"
        }
      }
    ],
    "next": "connect_stripe"
  }
}

What to do with it:

• readiness.sellable — true means buyers can purchase right now
• readiness.publishable — true means you can call publish_listing
• readiness.actions — list of what's blocking, each with kind: "api" or kind: "human"
  • api actions: the agent handles them (call the endpoint in resolve)
  • human actions: requires human input (show the message and url)
• readiness.next — the highest-priority action code to resolve first

The pattern: create_listing → get_listing → resolve each api action → surface human actions to the user → publish_listing when publishable is true.

---

Fulfillment Modes

ListBee supports two fulfillment modes, set at listing creation:

• Managed (STATIC) — set deliverable on the listing. ListBee auto-delivers the content to buyers on payment via an unlock page and email.
• Async agent (ASYNC) — set agent_callback_url on the listing. ListBee fires a webhook to your agent on payment; your agent calls fulfill_order with the generated content.

For ASYNC mode, use order_redeliver if your callback handler missed an event.

---

Debugging

Use MCP Inspector for interactive testing:

npx @modelcontextprotocol/inspector npx -y listbee-mcp

---

Get an API Key

console.listbee.so — sign in, go to API Keys.

---

Links

• API Reference — full endpoint docs
• OpenAPI Spec — machine-readable spec
• Docs — guides and integration examples
• CHANGELOG — version history
• npm — npm package
• GitHub — source

---

License

Apache-2.0