GunBroker MCP Server

GunBroker

GunBroker is a firearms and sporting-goods marketplace. Sellers run listings (auctions and buy-now), sold orders, and feedback queues; buyers search the public catalog.

First moves

1. Market search — keyword search across active listings when researching comps or pricing before you list.
2. Account snapshot — read connected seller account info when you need username or seller profile context.
3. Dashboard counts — queue depth at a glance (active listings, sold items, feedback pending) before drilling into lists.
4. Active inventory — list items currently selling; filter by time window when the user names "ending soon" or recent activity.
5. Sold inventory — list items sold or sold-order rows with time_frame and item_status filters for fulfillment triage.
6. Order detail — open a specific sold order when you have an order id from a list call.
7. Feedback — pull feedback queues for post-sale reputation follow-up.

Data model

Seller account → Listings (items) → Sold orders → Feedback. Items have item ids; sold workflows use order ids. Ended listings can be relisted from the source item id instead of drafting from scratch.

Operational order

1. Start with dashboard counts or a scoped items selling / items sold list — do not guess item or order ids.
2. Use search for market-wide discovery; seller inventory tools only cover the connected account.
3. For post-sale work, list sold orders or sold items with a time_frame (hours lookback) matching the user's date language.
4. Load order detail before updating status flags on that order.

Listing lifecycle

Upsert listings with one tool: omit item_id to create (optional jpg/gif pictures) or relist from source_item_id; pass item_id to patch an active listing. End listings early when pulling inventory (confirm_write=true).

Auction vs fixed-price listings need different required fields — gather category and pricing intent from the user before drafting.

Order fulfillment

Sold orders move through seller checkpoints: acknowledge, payment received, FFL received (when shipping to a licensed dealer), shipped, canceled, returned, refunded, or force-completed. OutdoorPay orders may not allow every payment flag — check order detail first. Cancel, return, and some terminal flags cannot be combined with other status updates in one step.

Gotchas

• FFL transfers — many firearms ship dealer-to-dealer; mark FFL received only after the receiving license is confirmed.
• Time frames — sold and selling list filters use hour-based lookback codes; map "last week" or "today" to an appropriate window.
• Pagination — list and search calls paginate; advance page index when the user asks for more results.
• Writes need confirmation — ending listings and mutating order status are destructive; expect confirm_write on seller mutations.