ShopsBuilder MCP Server

A Model Context Protocol implementation for interacting with ShopsBuilder e-commerce platform

Welcome to ShopsBuilder MCP

Connect, select, create, and manage a ShopsBuilder store

Connect an MCP client to this server's /mcp endpoint with Streamable HTTP. The server advertises OAuth metadata, so a standards-compatible client can open the sign-in flow without a client-supplied ShopsBuilder token. Client support and configuration vary; consult your client's documentation for remote OAuth MCP servers.

Connecting ShopsBuilder to LLMs allows you to easily get answers to questions like:

  • "Which products are running low on stock?"
  • "Customer insights from this month"
  • "Show recent orders that need attention"

This server is write-capable. Review tool inputs and confirm consequential changes before an agent submits them.

Getting Started

Quick setup guide to get you up and running

After OAuth authentication, call list_stores. With zero stores, collect name, language, email, and description; call create_store without confirmation to preview the input, show it to the user, then call it with confirmed=true only after approval. Exactly one store is selected automatically. With multiple stores, ask the user and call select_store. Use current_store to inspect the selection. If a management tool says provisioning is not ready, retry that tool shortly.

Bootstrap prompt: Set up my ShopsBuilder store. Authenticate through MCP OAuth, call list_stores, follow the zero, one, or multiple-store path, ask before creating or changing anything, and then use the existing management tools.

Available Tools

Pre-configured functions for common ShopsBuilder operations

Tools are pre-configured functions that can be used to help with common tasks. Each tool provides specific functionality for interacting with and managing your selected ShopsBuilder store.

Attach a presigned-upload key or public URL as a category image.

Arguments:

  • category_id (required) str:
  • key_or_public_url (required) str:
  • alt str | None:

Attach a public image URL as a category background image.

Arguments:

  • category_id (required) str:
  • source_url (required) str:
  • alt str | None:

Add a channel, and optionally countries, to a shipping zone.Attaching the channel alone is NOT enough to make stock visible. ShopsBuilder resolves availability through warehouses "operating in shipping zones that contain this country", so the zone must ALSO list the country the channel sells to. Attaching a GBP/GB channel to a zone whose countries are ``[US]`` leaves every product showing as out of stock while every other call still reports success.

Arguments:

  • shipping_zone_id (required) str:
  • channel_id (required) str:
  • add_countries list[str] | None:

Attach a real image to a product from any public image URL.This is the tool to use for product photos. ``add_product_media`` takes a ``media_url``, but ShopsBuilder's ``mediaUrl`` input is for embedding external VIDEO (YouTube/Vimeo) and rejects image URLs -- use this instead.

Arguments:

  • product_id (required) str:
  • source_url (required) str:
  • alt str | None:

Embed EXTERNAL VIDEO (YouTube/Vimeo) on a product. Not for images.This maps to ShopsBuilder's ``mediaUrl`` input, which only accepts recognised oEmbed video providers. Passing an image URL fails with UNSUPPORTED_MEDIA_PROVIDER, however valid and public the URL is.

Arguments:

  • product_id (required) str:
  • media_url (required) str:
  • alt str | None:

Attach real images to many products in one call.The tool to use when cataloguing a store: one image per product means one call per product otherwise, turning a 50 product import into 50 round-trips.

Arguments:

  • items (required) list[dict[str, str]]:

Attach an image you uploaded via ``create_presigned_upload_urls``.Completes the local-bytes flow: presign, PUT the bytes yourself, then call this with the returned ``key`` or ``public_url``.

Arguments:

  • product_id (required) str:
  • key_or_public_url (required) str:
  • alt str | None:

Add a product to the "Featured" collection shown on the public storefront.Get collection_id from ensure_featured_collection.

Arguments:

  • collection_id (required) str:
  • product_id (required) str:

Attach warehouses to a channel so its products can be sold.ShopsBuilder resolves ``quantityAvailable`` in channel context from the channel's own warehouse relation. A channel with no warehouses shows every product as out of stock regardless of warehouse stock levels, and this link is separate from the shipping-zone linkage -- attaching the zone to the channel does not create it. ``create_channel(warehouse_ids=[...])`` sets this at creation; use this tool to repair a channel that was created without it.

Arguments:

  • channel_id (required) str:
  • warehouse_ids (required) list[str]:

Fetch the list of channels from ShopsBuilder.This tools retrieves the list of channels. For each channel it returns information such as: ID, name, slug, currency code, default country, whether the channel is active, and the list of warehouses.

No additional arguments required

Diagnose why products in a channel are not buyable or show as out of stock.Verifies the whole availability chain and reports which link is broken:

Arguments:

  • channel (required) str:

Discount products or variants with a catalog promotion.Shoppers see the reduced price, with the original price struck through, in the listed channels from start_date until end_date. Confirm the products, the discount and the dates with the merchant first. Undo with delete_promotion; list existing ones with list_promotions.

Arguments:

  • name (required) str:
  • reward_value (required) float:
  • reward_value_type str:
  • product_ids list[str] | None:
  • variant_ids list[str] | None:
  • channel_ids list[str] | None:
  • start_date str | None:
  • end_date str | None:

Create a new category in ShopsBuilder.Args: ctx: MCP context for logging and request metadata name: Category name slug: URL-friendly slug (ShopsBuilder generates one from the name if not provided)

Arguments:

  • name (required) str:
  • slug str | None:

Create a new channel in ShopsBuilder.Pass ``warehouse_ids``. A channel with no warehouses sells nothing: ShopsBuilder resolves ``quantityAvailable`` in channel context from the channel's own warehouse relation, so every product shows as out of stock no matter how much stock the warehouse holds. Nothing else reports an error, and the warehouse being in a shipping zone attached to the channel is NOT enough -- the channel-warehouse link is separate.

Arguments:

  • name (required) str:
  • slug (required) str:
  • currency_code str:
  • default_country str:
  • is_active bool:
  • warehouse_ids list[str] | None:
  • shipping_zone_ids list[str] | None:

Get temporary upload URLs for product image files you hold locally.Use this only for local image files. For an image that already has a public URL, call add_product_image_from_url or add_product_media_bulk instead.

Arguments:

  • file_names (required) list[str]:
  • expires_in int:
  • max_bytes int:
  • upload_method str:

Create a product and return its ID plus the next catalog operation.Args: ctx: MCP context for logging and request metadata name: Name of the product (e.g., "OCR Credits - 2,000 Pages") product_type_id: ID of the product type slug: URL-friendly slug (optional) description: Optional Editor.js object serialized as JSON; it must contain a ``blocks`` array.

Arguments:

  • name (required) str:
  • product_type_id (required) str:
  • slug str | None:
  • description str | None:

Create a product type, the template that products of one kind share.Every product needs a product type; reuse one the store already has for the same kind of goods. For physical goods pass is_digital=false and is_shipping_required=true. Set has_variants=true when products of this type come in options such as size or colour.

Arguments:

  • name (required) str:
  • slug str | None:
  • is_digital bool:
  • is_shipping_required bool:
  • has_variants bool:

Create a product variant and return its ID plus the next catalog operation.Args: ctx: MCP context for logging and request metadata product_id: ID of the parent product sku: Stock Keeping Unit (e.g., "ocr-credits-2000") name: Variant name (optional) attributes: Product-type attribute IDs and this variant's values (optional)

Arguments:

  • product_id (required) str:
  • sku (required) str:
  • name str | None:
  • attributes list[ShopsBuilder_mcp.ShopsBuilder_client.input_types.AttributeValueInput] | None:

Create a new sale/discount in ShopsBuilder.Args: ctx: MCP context for logging and request metadata name: Name of the sale (e.g., "New Year Sale - 30% Off") sale_type: Type of discount - "PERCENTAGE" or "FIXED" variants: List of variant IDs to include in the sale products: List of product IDs to include in the sale start_date: Optional ISO date string for when sale starts end_date: Optional ISO date string for when sale ends

Arguments:

  • name (required) str:
  • sale_type str:
  • variants list[str] | None:
  • products list[str] | None:
  • start_date str | None:
  • end_date str | None:

Create a delivery option and price it in one or more channels.Without a shipping rate priced in the buyer's channel, checkout fails with "No shipping methods available for " no matter how correct the stock and zone setup is. This tool always sets the channel listings, so a rate cannot be created that is invisible to the channel it was meant for.

Arguments:

  • name (required) str:
  • shipping_zone_id (required) str:
  • channel_prices (required) list[dict[str, Any]]:
  • description str | None:
  • minimum_delivery_days int | None:
  • maximum_delivery_days int | None:

Preview or explicitly confirm creation of a marketplace-owned store.Ask for the store name, owner email, currency and selling countries. The currency can't be changed once the store has prices, so confirm it with the user. Language, label and descriptions keep Marketplace's defaults and can be changed after creation.

Arguments:

  • name (required) str:
  • email (required) str:
  • currency (required) CurrencyCode:
  • countries (required) list[CountryCode]:
  • confirmed bool:

Create a generic attribute dimension and assign it for variant selection.

Arguments:

  • product_type_id (required) str:
  • name (required) str:
  • values list[str] | None:
  • input_type VariantDimensionInputType:
  • slug str | None:

Return the current domain of the connected ShopsBuilder instance.

No additional arguments required

Return the selected store after fresh authorization revalidation.

No additional arguments required

Fetch list of customers from ShopsBuilder GraphQL API.This tool retrieves customer information such as: ID, active status, language code, last login, date joined, and default shipping/billing address country.

Arguments:

  • first int | None: Number of customers to fetch (max 100 per request)
  • after str | None: Cursor for pagination - fetch customers after this cursor
  • sort_by ShopsBuilder_mcp.ShopsBuilder_client.input_types.UserSortingInput | None: Sort customers by specific field
  • filter ShopsBuilder_mcp.tools.customers.CustomerFilterInput | None: Filter customers by specific criteria

Delete product images by media ID after the merchant confirms.Makes image mistakes recoverable: without this, a wrong or placeholder image attached during an import can only be removed from the dashboard. Find IDs with ``list_product_media``. Call without confirmation_token to get a preview and a token. Show the preview to the merchant, and only after they confirm call again with the same media_ids and the token.

Arguments:

  • media_ids (required) list[str]:
  • confirmation_token str | None:

Delete a promotion from ShopsBuilder after the merchant confirms.Call without confirmation_token to get a preview and a token. Show the preview to the merchant, and only after they confirm call again with the same promotion_id and the token.

Arguments:

  • promotion_id (required) str:
  • confirmation_token str | None:

Delete a sale/discount from ShopsBuilder after the merchant confirms.Call without confirmation_token to get a preview and a token. Show the preview to the merchant, and only after they confirm call again with the same sale_id and the token.

Arguments:

  • sale_id (required) str:
  • confirmation_token str | None:

Find or create the "Featured" collection and publish it in these channels.Get channel IDs from channels. If the store has several, ask the merchant which.

Arguments:

  • channel_ids (required) list[str]:

Get product pricing including discounts for a channel.Returns both the regular price and discounted price (if a sale applies) for all product variants in a channel.

Arguments:

  • channel str:
  • first int:

Discover assigned variant dimensions using one product or product type ID.

Arguments:

  • product_id str | None:
  • product_type_id str | None:

List all categories in ShopsBuilder.

No additional arguments required

List the images attached to a product, with their IDs.Use before ``delete_product_media`` to find the IDs to remove, or to check whether a product still needs an image.

Arguments:

  • product_id (required) str:

List all promotions in ShopsBuilder.

No additional arguments required

List all sales/discounts in ShopsBuilder.Args: ctx: MCP context for logging and request metadata channel: Optional channel slug to filter sales by channel

Arguments:

  • channel str | None:

List shipping rates and, crucially, which channels each is priced in.A rate only offers delivery in a channel it has a channel listing for. A zone can hold rates that are invisible to a given channel, which surfaces on the storefront as "No shipping methods available for " even though the zone, warehouse and stock are all correct.

Arguments:

  • shipping_zone_id str | None:

List all shipping zones in ShopsBuilder.The ``countries`` field matters: ShopsBuilder resolves stock availability through warehouses operating in a shipping zone that *contains the buyer's country*. A zone whose countries do not include the country a channel sells to will make every product in that channel show as out of stock, even when the warehouse holds stock.

No additional arguments required

List every store owned by the authenticated marketplace identity.

No additional arguments required

List all warehouses in ShopsBuilder.

No additional arguments required

Fetch total count of orders from ShopsBuilder GraphQL API.This tool retrieves the total count of orders based on the provided filter criteria.

Arguments:

  • filter ShopsBuilder_mcp.tools.orders.OrderFilterInput | None: Filter and search orders by specific criteria

Fetch list of orders from ShopsBuilder GraphQL API.This tool retrieves the list of orders. For each order it returns information such as: ID, number, status, creation date, last update date, payment status, total amount, shipping and billing address country, order lines which include: quantity, product SKU, variant name, product ID, product name, unit price. `placedVia` is "AI agent ()" for orders a shopper's AI agent placed through the shop's UCP endpoint, and null for orders placed in the storefront.

Arguments:

  • first int | None: Number of orders to fetch (max 100 per request)
  • after str | None: Cursor for pagination - fetch orders after this cursor
  • sort_by ShopsBuilder_mcp.ShopsBuilder_client.input_types.OrderSortingInput | None: Sort orders by specific field
  • filter ShopsBuilder_mcp.tools.orders.OrderFilterInput | None: Filter and search orders by specific criteria

Report which payment methods each channel's checkout accepts.Covers cards (Stripe), crypto and manual payment. Each method has a status: ready (shoppers can pay with it), needs_setup (installed but not configured for the channel), installed_unverified (installed; it can only be checked once the channel has an order) or not_connected. Every method that isn't ready has a connectUrl: send the merchant there to connect it in the browser. Never ask for API keys, secret keys or wallet details in chat.

No additional arguments required

Fetch list of products from ShopsBuilder GraphQL API.This tool retrieves product information such as: ID, name, slug, external reference, product type, category, date of creation, date of last update, and pricing.

Arguments:

  • first int | None: Number of products to fetch (max 100 per request)
  • after str | None: Cursor for pagination - fetch products after this cursor
  • channel str | None: Slug of a channel for which the data should be returned. If not provided, general product data is returned.
  • sort_by ShopsBuilder_mcp.ShopsBuilder_client.input_types.ProductOrder | None: Sort products by specific field
  • search str | None: Search products with full-text search

Publish a categorized product and return the next catalog operation.Args: ctx: MCP context for logging and request metadata product_id: ID of the product to publish channel_id: ID of the channel to publish to is_published: Whether the product is published (default: True) is_available_for_purchase: Whether available for purchase (default: True) visible_in_listings: Whether visible in listings (default: True)

Arguments:

  • product_id (required) str:
  • channel_id (required) str:
  • is_published bool:
  • is_available_for_purchase bool:
  • visible_in_listings bool:

Record a merchant request that no ShopsBuilder tool supports.Call this when the merchant asks for something none of the tools can do, after telling them plainly that it isn't supported yet. The ShopsBuilder team reviews these reports to decide what to build next. Do not call it for errors from a tool that exists.

Arguments:

  • request (required) str:
  • closest_tool str | None:

Assess what to restock from units sold and stock available now.Per variant: units sold in the window, average units per day, available stock (on hand minus allocated to unfulfilled orders), days of cover at that rate, a flag (out_of_stock, low, ok, no_sales) and suggestedRestock, the units to add to cover target_cover_days. Each warehouse row has its on-hand quantity. When suggestedRestock is above 0, restockPlan puts all of it into one warehouse (the one with the most on hand): warehouseId and setOnHandTo, the absolute quantity for set_variant_stock. Other warehouses stay unchanged.

Arguments:

  • days typing.Literal[7, 14, 30, 90]: Sales window in days, ending today (UTC)
  • low_cover_days int:
  • target_cover_days int:

Summarise the shop's sales for the last 7 or 30 days.Returns, for the period ending today (UTC dates, inclusive) and for the previous period of the same length: the order count, revenue per currency (order totals, gross) and the top 5 products by quantity sold. Cancelled, draft and expired orders are excluded. Use it to answer "how is my shop doing?" instead of paging through orders.

Arguments:

  • days typing.Literal[7, 30]: Length of the period in days, ending today (UTC)

Select a store only after fresh marketplace membership validation.

Arguments:

  • shop_id (required) int:

Publish a collection in channels or hide it from them.Removing a channel hides the collection from shoppers there and drops its channel publication settings, so a call with remove_channel_ids first returns a preview and a token. Show the preview to the merchant, and only after they confirm call again with the same arguments and the token. Get channel IDs from channels.

Arguments:

  • collection_id (required) str:
  • add_channel_ids list[str] | None:
  • remove_channel_ids list[str] | None:
  • confirmation_token str | None:

Price an existing shipping rate in one or more channels.Use to make an existing rate available in a channel it was not priced in -- the usual cause of "No shipping methods available for " when a zone already has rates. Find rate IDs with ``list_shipping_rates``.

Arguments:

  • shipping_rate_id (required) str:
  • channel_prices (required) list[dict[str, Any]]:

Set a variant's channel price and return the next catalog operation.Args: ctx: MCP context for logging and request metadata variant_id: ID of the product variant channel_id: ID of the channel price: Price amount (e.g., 20.00)

Arguments:

  • variant_id (required) str:
  • channel_id (required) str:
  • price (required) float:

Set variant stock and return the final catalog-media operation.Args: ctx: MCP context for logging and request metadata variant_id: ID of the product variant warehouse_id: ID of the warehouse quantity: Stock quantity (default: 999999 for unlimited digital products)

Arguments:

  • variant_id (required) str:
  • warehouse_id (required) str:
  • quantity int:

Fetch list of stocks from ShopsBuilder GraphQL API.This tool retrieves stock information such as: ID, quantity, allocated quantity, warehouse information, and associated product variant details.

Arguments:

  • first int | None: Number of stocks to fetch (max 100 per request)
  • after str | None: Cursor for pagination - fetch stocks after this cursor
  • filter ShopsBuilder_mcp.ShopsBuilder_client.input_types.StockFilterInput | None: Filter stocks by specific criteria

Assign a category to a product and return the next catalog operation.Args: ctx: MCP context for logging and request metadata product_id: ID of the product to update category_id: ID of the category to assign

Arguments:

  • product_id (required) str:
  • category_id (required) str:

Update the discount value for a sale in a specific channel.Args: ctx: MCP context for logging and request metadata sale_id: ID of the sale to update channel_id: ID of the channel discount_value: Discount value (percentage or fixed amount depending on sale type)

Arguments:

  • sale_id (required) str:
  • channel_id (required) str:
  • discount_value (required) float:

Add or remove the countries a shipping zone (and so the store) sells to.Use this when the merchant wants to start or stop selling to a country after the store was created. Shoppers in a country can only buy when a shipping zone assigned to the channel lists that country, so removing a country stops sales there; adding one makes stock in the zone's warehouses available there. So a call that removes countries first returns a preview and a token. Show the preview to the merchant, and only after they confirm call again with the same arguments and the token.

Arguments:

  • shipping_zone_id (required) str:
  • add_countries list[str] | None:
  • remove_countries list[str] | None:
  • confirmation_token str | None:

Update editable metadata for currently selected, freshly authorized shop.Every supplied field and language is saved together or not at all. Limits match the Builder: name 60, short description 160, description 1000 characters; hours are "HH:MM-HH:MM" or "closed".

Arguments:

  • background_image list[ShopsBuilder_mcp.marketplace.models.AttachmentInput] | None:
  • logo list[ShopsBuilder_mcp.marketplace.models.AttachmentInput] | None:
  • open_hours ShopsBuilder_mcp.marketplace.models.OpeningHoursInput | None:
  • links list[ShopsBuilder_mcp.marketplace.models.LinkInput] | None:
  • name_translations dict[ShopsBuilder_mcp.ShopsBuilder_client.enums.LanguageCodeEnum, typing.Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MaxLen(max_length=60)])]] | None:
  • short_description_translations dict[ShopsBuilder_mcp.ShopsBuilder_client.enums.LanguageCodeEnum, typing.Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MaxLen(max_length=160)])]] | None:
  • description_translations dict[ShopsBuilder_mcp.ShopsBuilder_client.enums.LanguageCodeEnum, typing.Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MaxLen(max_length=1000)])]] | None:

Fetch warehouse details from ShopsBuilder GraphQL API.This tool retrieves detailed warehouse information including: ID, name, slug, address details, click and collect options, associated shipping zones with their channels and countries, and metadata.

Arguments:

  • id str | None: ID of the warehouse to fetch details for

Built with ❤️ and 🤖 by ShopsBuilder Commerce.

Version: 0.1.3