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

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)

Account

Listings

Orders

Stripe

API Keys

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