VendBro MCP Server

Model Context Protocol server that exposes the VendBro card-scanning and inventory API to AI assistants (Claude Desktop, Cursor, Zed, and any other MCP-capable client).

Tools

15 tools, organized by workflow:

Scans

• vendbro_list_scans — recent scan history (scan:read)
• vendbro_add_scan — record one scan (scan:write)
• vendbro_add_scans_bulk — batch up to 1000 at once, for CSV/external imports (scan:write)
• vendbro_update_scan_sold_price — retroactively log a sale (scan:write)

Sessions

• vendbro_list_sessions — named scan buckets (sessions:read)
• vendbro_create_session — start a new bucket (sessions:write)

Inventory

• vendbro_list_inventory — cards held for sale (inventory:read)
• vendbro_upsert_inventory — add / update by SKU (inventory:write)
• vendbro_update_inventory — patch specific fields (inventory:write)
• vendbro_sell_inventory — mark sold at price, keeps history (inventory:write)
• vendbro_delete_inventory — hard delete, prefer sell (inventory:write)

Recognition & pricing

• vendbro_lookup_card — metadata + prices by name (no scope, free)
• vendbro_jp_price_lookup — PriceCharting data for JP cards (no scope, free)
• vendbro_recognize_card — identify from image (recognize; counts against scan quota)

Analytics

• vendbro_sales_stats — revenue, sale count, avg price (sales:read)

All calls run as the user who generated the API key, scoped by whatever permissions they selected when creating it. API access requires a paid subscription — free-tier users get 403 on every tool call.

1. Get an API key

Sign in at https://app.vendbro.com, open your profile → API Keys → Create key. Copy the full vb_live_… token — it's shown once.

Recommended default scopes (the "Create" button picks all of these):

• scan:read, scan:write
• sessions:read, sessions:write
• inventory:read, inventory:write
• recognize

Scope down for narrower integrations (e.g. read-only analytics bot).

2. Install

Option A: via npx (recommended — no clone needed)

Nothing to install. Your MCP client will fetch the package at startup:

{
  "mcpServers": {
    "vendbro": {
      "command": "npx",
      "args": ["-y", "@vendbro/mcp-server"],
      "env": {
        "VENDBRO_API_KEY": "vb_live_your_key_here"
      }
    }
  }
}

Option B: from source (for local hacking)

git clone https://github.com/netmana808/Poke-Scan.git
cd Poke-Scan/mcp-server
npm install
npm run build

Then point your MCP client at node /absolute/path/to/mcp-server/dist/index.js.

3. Wire into your MCP client

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows). Use the npx config snippet from Option A above.

Restart Claude Desktop. The tools appear under the hammer icon.

Cursor / Zed / others

Any MCP client that spawns a stdio subprocess works. Same config shape — just drop it into the client's MCP settings block.

4. Optional env

• VENDBRO_API_BASE — override the API root. Defaults to https://api.vendbro.com/api. Set to http://localhost:3002/api to hit a local backend.

Troubleshooting

"VENDBRO_API_KEY not set" — the env var didn't reach the subprocess. Double-check the env block in your MCP client config; some clients require absolute paths in the command.

VendBro API error 401 on a specific tool — the key is valid but doesn't carry the scope that tool needs. Go back to the API Keys page, revoke, and create a new one with the right scopes. Revokes propagate in ~60 seconds.

VendBro API error 429 on vendbro_recognize_card — the user hit their daily scan quota. Free tier gets a modest daily limit; Pro is unlimited.

Security notes

• The key is stored in plain text in your MCP client config. Treat it like a password — anyone with read access to that file can act as you.
• The server never logs the key itself (stderr startup message shows the API base URL only).
• Revoke keys any time via the API Keys page — takes effect in ≤60s.

License

Apache 2.0 (same as the main repo).