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