How do I use bol-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@bol-mcp Show my open orders from last week" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

bol-mcp

by BartWaardenburg

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

bol-mcp

Een Model Context Protocol (MCP) server voor de bol.com Retailer API. Beheer bestellingen, aanbiedingen, verzendingen, retouren, facturen en commissies — allemaal via natuurlijke taal in je AI-app.

Let op: Dit is een onofficieel, community-onderhouden project en is niet verbonden aan of goedgekeurd door bol.com.

A community-built Model Context Protocol (MCP) server for the bol.com Retailer API. Manage orders, offers, shipments, returns, invoices, and commissions — all through natural language via any MCP-compatible AI client.

Note: This is an unofficial, community-maintained project and is not affiliated with or endorsed by bol.com.

Snel starten

Je hoeft deze repo niet te clonen.

Zorg dat Node.js 20+ is geïnstalleerd (je AI-app draait npx op je machine)
Haal bol.com API-gegevens op (zie Authentication)
Voeg de server toe als MCP server in je AI-app (kopieer onderstaande configuratie)
Stel vragen in gewoon Nederlands (zie Voorbeelden)

Related MCP server: wefact-mcp

Quick Start (Non-Developers)

You do not need to clone this repo.

Make sure Node.js 20+ is installed (your AI app will run npx on your machine)
Get bol.com API credentials (see Authentication)
Add the server to your AI app as an MCP server (copy/paste config below)
Ask in plain language (see Example Usage)

Add To Claude Desktop (Also Works In Cowork)

Cowork runs inside Claude Desktop and uses the same connected MCP servers and permissions.

Open your Claude Desktop MCP config file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\\Claude\\claude_desktop_config.json
Add this server entry (or merge it into your existing mcpServers):

{
  "mcpServers": {
    "bol-mcp": {
      "command": "npx",
      "args": ["-y", "bol-mcp"],
      "env": {
        "BOL_CLIENT_ID": "your-client-id",
        "BOL_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Restart Claude Desktop

Add To Other AI Apps

Most MCP apps have a screen like "Add MCP Server" where you can fill in:

Command: npx
Args: -y bol-mcp
Env: BOL_CLIENT_ID=your-client-id and BOL_CLIENT_SECRET=your-client-secret

If your app wants JSON, paste this and adapt the top-level key name to your client (common ones are mcpServers, servers, or context_servers):

{
  "<servers-key>": {
    "bol-mcp": {
      "command": "npx",
      "args": ["-y", "bol-mcp"],
      "env": {
        "BOL_CLIENT_ID": "your-client-id",
        "BOL_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Troubleshooting

Error: Missing required env vars: BOL_CLIENT_ID, BOL_CLIENT_SECRET
- Fix: add both env vars to the MCP server config and restart your app.
Error: npx: command not found or server fails to start
- Fix: install Node.js 20+ and restart your app.
You can connect, but API calls fail with 401/403
- Fix: verify client ID/secret are correct and active in the bol.com Seller Dashboard.

API Coverage

bol.com exposes several APIs for different purposes. This MCP server covers the Retailer API v10 and the Shared API — the core APIs for marketplace sellers managing their day-to-day operations.

API	Status	Description
Retailer API v10	Covered	Core seller operations: orders, offers, shipments, returns, invoices, commissions, products, inventory, promotions, replenishments, subscriptions, and more
Shared API v10	Covered	Cross-API utilities for tracking asynchronous process statuses
Offer API v11	Not covered	Next-generation offer management (v11 successor to the Retailer API offer endpoints)
Advertiser API v11	Not covered	Sponsored product campaigns, ad groups, keywords, budgets, and performance reporting
Economic Operators API	Not covered	Economic operator information and regulatory compliance data

The Retailer API v10 offer endpoints included in this MCP are fully functional. The Offer API v11 is a newer version with an updated endpoint structure — support may be added in a future release.

Features

76 tools across 17 categories covering the bol.com Retailer API v10
Order management — list, inspect, and cancel orders with status and fulfilment filtering
Offer CRUD — create, update, delete offers with price/stock management and export reports
Shipment handling — create shipments with partial quantity support and invoice requests
Return processing — list, inspect, create, and handle returns
Invoice access — retrieve invoices by period with full UBL detail and specifications
Commission calculator — single and bulk commission rates by EAN, condition, and price
Product catalog — browse categories, search products, view competing offers, ratings, and assets
Product content — manage catalog content, upload reports, and chunk recommendations
Insights — offer visits, buy box %, performance indicators, product ranks, sales forecasts, and search terms
Inventory — LVB/FBB inventory levels with filtering
Promotions — list and inspect promotions and their products
Replenishments — full FBB replenishment lifecycle: create, update, delivery dates, pickup slots, labels
Retailers — retailer account information
Shipping labels — delivery options and label creation
Subscriptions — webhook/pubsub/SQS event subscriptions with signature key management
Transports — update transport tracking information
Process status — track asynchronous operations by ID, entity, or in bulk
OAuth2 authentication with automatic token refresh
Input validation via Zod schemas on every tool for safe, predictable operations
Response caching with configurable TTL and automatic invalidation on writes
Rate limit handling with exponential backoff and Retry-After header support
Toolset filtering to expose only the tool categories you need
Docker support for containerized deployment
Actionable error messages with context-aware recovery suggestions

Supported Clients

This MCP server is not tied to one coding agent. It works with any MCP-compatible client or agent runtime that can start a stdio MCP server.

Client / runtime	Docs
Claude Code	MCP in Claude Code
Anthropic API (Messages API)	Remote MCP servers
Codex CLI (OpenAI)	Codex CLI docs
Gemini CLI (Google)	Gemini CLI MCP server docs
VS Code (Copilot)	Use MCP servers in VS Code
Claude Desktop	MCP in Claude Desktop
Cursor	Cursor docs
Windsurf	Windsurf MCP docs
Cline	Cline MCP docs
Zed	Zed context servers docs
Any other MCP host	Use command/args/env from Generic MCP Server Config

Claude Ecosystem Notes

Claude currently has multiple MCP-related concepts that are easy to mix up:

Local MCP servers (Claude Desktop): defined in claude_desktop_config.json and started on your machine (docs).
Cowork: reuses the MCP servers connected in Claude Desktop (docs).
Connectors: remote MCP integrations managed in Claude (docs).
Cowork plugins: Claude-specific workflow packaging (instructions + tools/data integrations) (docs). Useful in Claude, but not portable as a generic MCP server config for other agent clients.

Verified against vendor docs on 2026-03-05.

Setup (Power Users)

If Quick Start worked in your client, you can skip this section. These are additional per-client setup options and CLI one-liners.

Generic MCP Server Config

Use this as the baseline in any host:

Command: npx
Args: ["-y", "bol-mcp"]
Required env vars: BOL_CLIENT_ID, BOL_CLIENT_SECRET
Optional env vars: BOL_CACHE_TTL, BOL_MAX_RETRIES, BOL_TOOLSETS (see Configuration)

Minimal JSON (adapt the top-level key to your host):

{
  "<servers-key>": {
    "bol-mcp": {
      "command": "npx",
      "args": ["-y", "bol-mcp"],
      "env": {
        "BOL_CLIENT_ID": "your-client-id",
        "BOL_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Host key mapping:

Host	Top-level key	Notes
VS Code	`servers`	Add `"type": "stdio"` on the server object
Claude Desktop / Cursor / Windsurf / Cline	`mcpServers`	Same command/args/env block
Zed	`context_servers`	Same command/args/env block
Codex CLI (TOML)	`mcp_servers`	Uses TOML, shown below

Claude Code

claude mcp add --scope user bol-mcp \
  --env BOL_CLIENT_ID=your-client-id \
  --env BOL_CLIENT_SECRET=your-client-secret \
  -- npx -y bol-mcp

Codex CLI (OpenAI)

codex mcp add bol-mcp \
  --env BOL_CLIENT_ID=your-client-id \
  --env BOL_CLIENT_SECRET=your-client-secret \
  -- npx -y bol-mcp

~/.codex/config.toml alternative:

[mcp_servers.bol-mcp]
command = "npx"
args = ["-y", "bol-mcp"]
env = { "BOL_CLIENT_ID" = "your-client-id", "BOL_CLIENT_SECRET" = "your-client-secret" }

Gemini CLI (Google)

gemini mcp add bol-mcp -- npx -y bol-mcp

Set BOL_CLIENT_ID and BOL_CLIENT_SECRET in ~/.gemini/settings.json.

VS Code (Copilot)

Open Command Palette (Cmd+Shift+P / Ctrl+Shift+P) > MCP: Add Server > Command (stdio), or use .vscode/mcp.json with top-level key servers and the canonical command/args/env block from Generic MCP Server Config.

Claude Desktop + Cowork / Cursor / Windsurf / Cline / Zed

Cowork runs inside Claude Desktop and uses the same connected MCP servers and permissions. Configure once in Claude Desktop, then the server is available in Cowork.

Use the canonical config block and place it in the host file below with the matching top-level key.

Client	Config location	Top-level key
Claude Desktop (macOS)	`~/Library/Application Support/Claude/claude_desktop_config.json`	`mcpServers`
Claude Desktop (Windows)	`%APPDATA%\\Claude\\claude_desktop_config.json`	`mcpServers`
Cursor (project)	`.cursor/mcp.json`	`mcpServers`
Cursor (global)	`~/.cursor/mcp.json`	`mcpServers`
Windsurf	`~/.codeium/windsurf/mcp_config.json`	`mcpServers`
Cline	MCP settings UI	`mcpServers`
Zed (macOS/Linux)	`~/.zed/settings.json` or `~/.config/zed/settings.json`	`context_servers`

Docker

docker run -i --rm \
  -e BOL_CLIENT_ID=your-client-id \
  -e BOL_CLIENT_SECRET=your-client-secret \
  ghcr.io/bartwaardenburg/bol-mcp

Other MCP Clients

Use the values from Generic MCP Server Config.

Terminology

What is portable across hosts:

MCP server runtime settings (command, args, env)
Transport model (stdio command server)
Tool names and tool schemas exposed by this server

What is host/vendor-specific (not portable as-is):

Host config key names (servers, mcpServers, context_servers, mcp_servers)
Host UX/workflows for adding servers (CLI commands, UI menus, settings paths)
Anthropic-specific concepts such as Claude Desktop local MCP servers, Claude Connectors via remote MCP, and Claude Code plugins used in Cowork workflows

Security Notes

Trust model: Any prompt or agent allowed to call this MCP server can execute bol.com API actions with the configured credentials.
Least-privilege credentials: Use separate bol.com API credentials per environment/team/use case and rotate/revoke when access changes.
Write-action approvals: Enable host-side approvals for mutating tools (create_*, update_*, delete_*, cancel_*, handle_return, shipment/replenishment actions).
Team config governance: Keep shared MCP config in version control, require review for changes to command/args/env/toolset filtering, and keep secrets in a vault or host secret manager (not in plain-text repo files).

Configuration

Required

Variable	Description
`BOL_CLIENT_ID`	Your bol.com API client ID
`BOL_CLIENT_SECRET`	Your bol.com API client secret

Generate your credentials in the bol.com Partner Platform under Settings > API Settings.

Optional

Variable	Description	Default
`BOL_CACHE_TTL`	Response cache lifetime in seconds. Set to `0` to disable caching.	`120`
`BOL_MAX_RETRIES`	Maximum retry attempts for rate-limited (429) requests with exponential backoff.	`3`
`BOL_TOOLSETS`	Comma-separated list of tool categories to enable (see Toolset Filtering).	All toolsets

Authentication

This server authenticates with the bol.com Retailer API using the OAuth2 client credentials flow. It automatically obtains and refreshes access tokens — you only need to provide your client ID and secret.

For full details, see the official bol.com authentication documentation.

Creating Your Credentials

Log in to the bol.com Seller Dashboard
Navigate to Settings > Services > API Settings
Provide technical contact details (required before creating credentials)
Create a new API credential set
Copy the Client ID and Client Secret

How It Works

The server exchanges your credentials for a short-lived access token via the bol.com token endpoint:

Endpoint: POST https://login.bol.com/token
Auth: HTTP Basic with base64(clientId:clientSecret)
Grant type: client_credentials
Token lifetime: ~5 minutes (299 seconds)

Tokens are automatically reused and refreshed before expiry — no manual token management required.

Security Best Practices

See Security Notes. bol.com-specific credential hygiene:

Never share your client ID or client secret, and don't hardcode them in source files
Use environment variables or host secret stores to pass credentials
Revoke and replace credentials immediately if compromise is suspected

Available Tools

Orders

Tool	Description
`list_orders`	List orders with optional status and fulfilment method filtering
`get_order`	Get detailed order information by order ID
`cancel_order_items`	Cancel order items with a reason code

Offers

Tool	Description
`get_offer`	Get offer details by offer ID
`create_offer`	Create a new offer (EAN, condition, price, stock, fulfilment method)
`update_offer`	Update offer details (reference, onHoldByRetailer, unknown product title, fulfilment)
`delete_offer`	Delete an offer permanently
`update_offer_price`	Update the pricing for an offer
`update_offer_stock`	Update the stock level for an offer
`request_offer_export`	Request a CSV export of all offers
`get_offer_export`	Download a previously requested offer export
`request_unpublished_offer_report`	Request a report of unpublished offers
`get_unpublished_offer_report`	Download a previously requested unpublished offer report

Shipments

Tool	Description
`list_shipments`	List shipments with optional order ID and fulfilment method filtering
`get_shipment`	Get shipment details by shipment ID
`create_shipment`	Create a shipment for order items (supports partial quantities)
`get_shipment_invoice_requests`	List invoice requests for shipments

Returns

Tool	Description
`list_returns`	List returns with optional handled status and fulfilment method filtering
`get_return`	Get return details by RMA ID
`handle_return`	Handle/process a return (accept, reject, repair, etc.)
`create_return`	Create a return for an order item

Invoices

Tool	Description
`list_invoices`	List invoices by date period (max 31 days, format: YYYY-MM-DD)
`get_invoice`	Get full invoice details by invoice ID
`get_invoice_specification`	Get detailed invoice specification/line items

Commissions

Tool	Description
`get_commission`	Calculate the commission for a product by EAN, condition, and unit price
`get_bulk_commissions`	Calculate commissions for multiple products at once

Products

Tool	Description
`get_product_categories`	Browse product categories
`get_product_list`	Search and browse products by category or search term
`get_product_list_filters`	Get available product list filters
`get_product_assets`	Get product images and assets by EAN
`get_competing_offers`	Get competing offers for a product by EAN
`get_product_placement`	Get product placement information
`get_price_star_boundaries`	Get price star boundaries for a product
`get_product_ids`	Get product identifiers by EAN
`get_product_ratings`	Get product ratings and reviews

Product Content

Tool	Description
`get_catalog_product`	Get catalog product details by EAN
`create_product_content`	Create or update product content
`get_upload_report`	Get product content upload report
`get_chunk_recommendations`	Get product content recommendations

Insights

Tool	Description
`get_offer_insights`	Get offer visit and buy box insights
`get_performance_indicators`	Get retailer performance indicators
`get_product_ranks`	Get product search and browse rankings
`get_sales_forecast`	Get sales forecast for an offer
`get_search_terms`	Get search term volume data

Inventory

Tool	Description
`get_inventory`	Get LVB/FBB inventory with filtering by stock level, state, and EAN

Promotions

Tool	Description
`list_promotions`	List available promotions by type
`get_promotion`	Get promotion details
`get_promotion_products`	Get products in a promotion

Replenishments

Tool	Description
`list_replenishments`	List FBB replenishments with filtering
`get_replenishment`	Get replenishment details
`create_replenishment`	Create a new FBB replenishment
`update_replenishment`	Update or cancel a replenishment
`get_delivery_dates`	Get available FBB delivery dates
`get_pickup_time_slots`	Get pickup time slots for a delivery date
`request_product_destinations`	Request product warehouse destinations
`get_product_destinations`	Get product warehouse destinations

Retailers

Tool	Description
`get_retailer_information`	Get retailer account information

Shipping Labels

Tool	Description
`get_delivery_options`	Get available shipping/delivery options for order items
`create_shipping_label`	Create a shipping label for order items

Subscriptions

Tool	Description
`list_subscriptions`	List all event subscriptions
`get_subscription`	Get subscription details
`create_subscription`	Create an event subscription (webhook, GCP Pub/Sub, or AWS SQS)
`update_subscription`	Update an event subscription
`delete_subscription`	Delete an event subscription
`test_subscription`	Send a test notification to a subscription
`get_signature_keys`	Get public keys for webhook signature validation

Transports

Tool	Description
`update_transport`	Update transport/tracking information

Process Status

Tool	Description
`get_process_status`	Get the status of an asynchronous process by process status ID
`get_process_status_by_entity`	Get process statuses by entity ID and event type
`get_process_status_bulk`	Get the status of multiple processes by their IDs (up to 1000)

Toolset Filtering

Reduce context window usage by enabling only the tool categories you need. Set the BOL_TOOLSETS environment variable to a comma-separated list:

BOL_TOOLSETS=orders,offers

Toolset	Tools included
`orders`	Order listing, details, and cancellation
`offers`	Full offer CRUD, price/stock management, export reports
`shipments`	Shipment listing, details, creation, and invoice requests
`returns`	Return listing, details, creation, and handling
`invoices`	Invoice listing, details, and specifications
`commissions`	Single and bulk commission calculation
`products`	Product categories, search, assets, competing offers, ratings, placement
`product-content`	Catalog products, content creation, upload reports, recommendations
`insights`	Offer insights, performance indicators, product ranks, sales forecasts, search terms
`inventory`	LVB/FBB inventory levels
`promotions`	Promotion listing and product details
`replenishments`	FBB replenishment lifecycle, delivery dates, pickup slots, destinations
`retailers`	Retailer account information
`shipping-labels`	Delivery options and shipping label creation
`subscriptions`	Event subscription management and signature keys
`transports`	Transport tracking updates
`process-status`	Asynchronous process status tracking (by ID, entity, or bulk)

When not set, all toolsets are enabled. Invalid names are ignored; if all names are invalid, all toolsets are enabled as a fallback.

Voorbeelden

Eenmaal verbonden kun je in gewoon Nederlands vragen stellen:

"Toon al mijn openstaande bestellingen"
"Geef de details van bestelling 1234567890"
"Maak een aanbieding voor EAN 9781234567890 voor 19,99 EUR met 50 stuks op voorraad"
"Werk de voorraad bij voor aanbieding abc-123 naar 25 stuks"
"Verzend orderitems voor bestelling 1234567890 met transportcode TNT"
"Toon alle onbehandelde retouren"
"Wat is de commissie op EAN 9781234567890 bij 29,99 EUR?"
"Toon mijn facturen van januari 2025"

Example Usage

Once connected, you can interact with the bol.com API using natural language:

"List all my open orders"
"Show me the details of order 1234567890"
"Create an offer for EAN 9781234567890 at 19.99 EUR with 50 units in stock"
"Update the stock for offer abc-123 to 25 units"
"Ship order items for order 1234567890 with transport code TNT"
"Show me all unhandled returns"
"What's the commission on EAN 9781234567890 at 29.99 EUR?"
"List my invoices for January 2025"

Community

Support: SUPPORT.md
Security reporting: SECURITY.md
Contributing guidelines: CONTRIBUTING.md
Bug reports and feature requests: Issues

Development

# Install dependencies
pnpm install

# Run in development mode
pnpm dev

# Build for production
pnpm build

# Run tests
pnpm test

# Type check
pnpm typecheck

Project Structure

src/
  index.ts              # Entry point (stdio transport)
  server.ts             # MCP server setup and toolset filtering
  bol-client.ts         # bol.com API HTTP client with OAuth2, caching, and retry
  cache.ts              # TTL-based in-memory response cache
  types.ts              # TypeScript interfaces for bol.com API v10
  tool-result.ts        # Error formatting with recovery suggestions
  update-checker.ts     # NPM update notifications
  tools/
    orders.ts           # Order listing, details, and cancellation
    offers.ts           # Offer CRUD, pricing, stock, and export reports
    shipments.ts        # Shipment listing, details, creation, and invoices
    returns.ts          # Return listing, details, creation, and handling
    invoices.ts         # Invoice listing, details, and specifications
    commissions.ts      # Single and bulk commission calculation
    products.ts         # Product catalog, search, competing offers, ratings
    product-content.ts  # Catalog content management and recommendations
    insights.ts         # Offer insights, performance, ranks, forecasts
    inventory.ts        # LVB/FBB inventory management
    promotions.ts       # Promotion listing and products
    replenishments.ts   # FBB replenishment lifecycle
    retailers.ts        # Retailer account information
    shipping-labels.ts  # Delivery options and label creation
    subscriptions.ts    # Event subscription management
    transports.ts       # Transport tracking updates
    process-status.ts   # Asynchronous process status tracking

Requirements

Node.js >= 20
A bol.com seller account with API credentials

License

MIT - see LICENSE for details.

Available Tools

76 tools

cancel_order_itemCancel Order ItemA

Destructive

Cancel an order item by order item ID. Can be used to confirm a customer cancellation request or to cancel an item you cannot fulfil. Returns a process status — the cancellation is processed asynchronously. Always review the order with get_order before cancelling.

Inputs: orderItemId (required), reasonCode (required).

create_offerCreate OfferA

Create a new offer on bol.com. Requires EAN, condition, pricing (at least one bundle price with quantity 1), stock, and fulfilment method. Returns a process status — the offer is created asynchronously. Use get_process_status to check completion.

Inputs: ean (required), condition (required), pricing (required), stock (required), +5 more.

create_product_contentCreate Product ContentB

Create or update product content for a given EAN. Provide product attributes such as title, description, brand, etc. Returns a process status — the content is created asynchronously. Use get_process_status to check completion.

Inputs: language (required), attributes (required), assets.

create_replenishmentCreate FBB ReplenishmentA

Create a new FBB (Fulfilled by bol.com) replenishment. Provide a reference, delivery date, and lines with EAN and quantity. Returns a process status — the replenishment is created asynchronously. Use get_process_status to check completion.

Inputs: reference (required), labelingByBol (required), numberOfLoadCarriers (required), lines (required), +2 more.

create_returnCreate ReturnA

Create a return and automatically handle it with the provided handling result. When successfully created, the resulting return ID is provided in the process status. Returns a process status — the return is created asynchronously.

Inputs: orderItemId (required), quantityReturned (required), handlingResult (required).

create_shipmentCreate ShipmentA

Create a shipment for one or more order items. You must provide the order item IDs and optionally transport details (transporter code and track & trace). Returns a process status — the shipment is created asynchronously. Use get_process_status to check completion. Always verify the order item IDs with get_order before creating a shipment.

Inputs: orderItems (required), shipmentReference, shippingLabelId, transport.

create_shipping_labelCreate Shipping LabelA

Create a shipping label for one or more order items. Requires a shippingLabelOfferId from get_delivery_options. Returns a process status — the label is created asynchronously. Use get_process_status to check completion.

Inputs: orderItems (required), shippingLabelOfferId (required).

create_subscriptionCreate SubscriptionA

Create a new event subscription. Subscribe to events like PROCESS_STATUS, SHIPMENT, PRICE_STAR_BOUNDARY, COMPETING_OFFER, OFFER_FOR_SALE, OFFER_NOT_FOR_SALE. Supports WEBHOOK, GCP_PUBSUB, and AWS_SQS subscription types.

Inputs: resources (required), url (required), subscriptionType (required), enabled, +1 more.

delete_offerDelete OfferA

Destructive

Delete an offer from bol.com. This permanently removes the offer — it cannot be undone. Always confirm with the user before calling this tool.

Inputs: offerId (required).

delete_subscriptionDelete SubscriptionA

Destructive

Delete an event subscription. This permanently removes the subscription — it cannot be undone. Always confirm with the user before calling this tool.

Inputs: subscriptionId (required).

get_bulk_commissionsGet Bulk CommissionsA

Read-only

Get commissions and possible reductions for multiple products in bulk. Provide EAN, unit price, and optionally condition for each product.

Inputs: commissionQueries (required).

get_catalog_productGet Catalog ProductA

Read-only

Get catalog product details by EAN, including product attributes, titles, and other catalog information.

Inputs: ean (required), language.

get_chunk_recommendationsGet Product Content RecommendationsC

Read-only

Get product content recommendations (chunk recommendations) for a given EAN. Provides suggestions for improving product content.

Inputs: attributes (required).

get_commissionGet CommissionA

Read-only

Get the commission for a product based on EAN, condition, and unit price. Returns the fixed amount, percentage, total cost, and any active reductions.

Inputs: ean (required), unitPrice (required), condition.

get_commission_ratesGet Commission Rates (BETA)A

Read-only

Get a list of all commission rates by EAN. Returns commission rate tables with price ranges and conditions. This is a BETA endpoint.

Inputs: products (required).

get_competing_offersGet Competing OffersA

Read-only

Get competing offers for a product by EAN. Shows offer details including pricing, condition, and seller information.

Inputs: ean (required), page, countryCode, bestOfferOnly, +2 more.

get_delivery_datesGet FBB Delivery DatesA

Read-only

Get available delivery dates for FBB (Fulfilled by bol.com) replenishments.

Inputs: no named parameters.

get_delivery_optionsGet Delivery OptionsA

Read-only

Get available delivery and shipping options for one or more order items. Shows available shipping methods with prices. Use the shippingLabelOfferId from the results when creating a shipping label.

Inputs: orderItems (required).

get_inventoryGet InventoryA

Read-only

Get LVB/FBB inventory list from bol.com. Returns inventory items with EAN, title, regular stock, and graded stock. Filter by quantity range, stock level, state, or search by EAN/product title.

Inputs: page, quantity, stock, state, +1 more.

get_invoiceGet Invoice DetailsA

Read-only

Get detailed information about a specific invoice.

Inputs: invoiceId (required).

get_invoice_requestsGet Invoice RequestsA

Read-only

Get a list of invoice requests initiated by customers for shipments. Filter by shipment ID or state (OPEN, UPLOAD_ERROR, ALL).

Inputs: shipmentId, page, state.

get_invoice_specificationGet Invoice SpecificationA

Read-only

Get an invoice specification with a paginated list of its transactions. The specification contains detailed line items for the invoice.

Inputs: invoiceId (required), page.

get_load_carrier_labelsGet Load Carrier LabelsA

Read-only

Get load carrier labels for a replenishment. Returns label data (PDF).

Inputs: replenishmentId (required), labelType.

get_offerGet Offer DetailsA

Read-only

Get detailed information about a specific offer including EAN, pricing, stock, fulfilment method, and condition.

Inputs: offerId (required).

get_offer_exportGet Offer ExportA

Read-only

Retrieve an offer export file by report ID. The report ID is obtained from the process status after requesting an export.

Inputs: reportId (required).

get_offer_insightsGet Offer InsightsA

Read-only

Get offer visit and buy box insights for a specific offer. Returns data like product visits or buy box percentage over the specified time period.

Inputs: offerId (required), period (required), numberOfPeriods (required), name (required).

get_orderGet Order DetailsA

Read-only

Get detailed information about a specific order including order items, shipping details, billing details, and fulfilment status.

Inputs: orderId (required).

get_performance_indicatorsGet Performance IndicatorsA

Read-only

Get retailer performance indicators for a specific week. Returns scores and details for metrics like cancellations, fulfilment, phone availability, etc.

Inputs: name (required), year (required), week (required).

get_pick_listGet Pick ListA

Read-only

Get the pick list for a replenishment. Returns pick list data (PDF).

Inputs: replenishmentId (required).

get_pickup_time_slotsGet Pickup Time SlotsA

Read-only

Get available pickup time slots for a given address and number of load carriers.

Inputs: address (required), numberOfLoadCarriers (required).

get_price_star_boundariesGet Price Star BoundariesA

Read-only

Get the price star boundaries for a product by EAN. Shows the price ranges that correspond to different star ratings.

Inputs: ean (required).

get_process_statusGet Process StatusA

Read-onlyIdempotent

Get the status of an asynchronous process by its process status ID. All PUT/POST/DELETE requests return a process status ID that can be used here to check completion.

Inputs: processStatusId (required).

get_process_status_bulkGet Process Status (Bulk)A

Read-onlyIdempotent

Get the status of multiple asynchronous processes by their process status IDs. Up to 1000 IDs can be queried in a single request.

Inputs: processStatusIds (required).

get_process_status_by_entityGet Process Status by EntityA

Read-onlyIdempotent

Get the status of asynchronous processes by entity ID and event type. The entity ID can be an order item ID, transport ID, return number, replenishment ID, etc. Results are returned in descending order.

Inputs: entityId (required), eventType (required), page.

get_product_assetsGet Product AssetsB

Read-only

Get product assets (images) for a product by EAN. Optionally filter by usage type.

Inputs: ean (required), usage.

get_product_categoriesGet Product CategoriesA

Read-only

Get the list of product categories available on bol.com. Returns categories with their IDs and names.

Inputs: language.

get_product_destinationsGet Product DestinationsA

Read-only

Get product warehouse destinations by product destinations ID. Use after requesting destinations with request_product_destinations.

Inputs: productDestinationsId (required).

get_product_idsGet Product IDsB

Read-only

Get the product identifiers for a product by EAN. Returns various IDs associated with the product.

Inputs: ean (required).

get_product_listGet Product ListA

Read-only

Search or browse products on bol.com by category or search term. Returns a list of products with EAN and title.

Inputs: countryCode, categoryId, searchTerm, page, +4 more.

get_product_list_filtersGet Product List FiltersA

Read-only

Get the available filters for browsing or searching products on bol.com.

Inputs: countryCode, searchTerm, categoryId, language.

get_product_placementGet Product PlacementA

Read-only

Get product placement information for a product by EAN.

Inputs: ean (required), countryCode, language.

get_product_ranksGet Product RanksA

Read-only

Get product search and browse ranking data for a specific EAN on a given date. Shows how a product ranks in search results and category browsing.

Inputs: ean (required), date (required), type, page, +1 more.

get_product_ratingsGet Product RatingsB

Read-only

Get ratings and reviews summary for a product by EAN. Shows the average rating and total number of reviews.

Inputs: ean (required).

get_promotionGet PromotionA

Read-only

Get detailed information about a specific promotion including its type, dates, and conditions.

Inputs: promotionId (required).

get_promotion_productsGet Promotion ProductsB

Read-only

Get the list of products participating in a specific promotion.

Inputs: promotionId (required), page.

get_replenishmentGet Replenishment DetailsA

Read-only

Get detailed information about a specific FBB replenishment including lines, state, delivery info, and load carriers.

Inputs: replenishmentId (required).

get_retailer_informationGet Retailer InformationA

Read-only

Get retailer information. Provide a retailer ID to look up a specific retailer, or omit it to get your own account information.

Inputs: retailerId.

get_returnGet Return DetailsA

Read-only

Get detailed information about a specific return including return items, reasons, tracking, and processing results.

Inputs: returnId (required).

get_sales_forecastGet Sales ForecastA

Read-only

Get sales forecast for a specific offer. Returns predicted sales volume for the specified number of weeks ahead (1-12).

Inputs: offerId (required), weeksAhead (required).

get_search_termsGet Search TermsA

Read-only

Get search term volume data from bol.com. Returns how often a search term is used over the specified time period, optionally including related search terms.

Inputs: searchTerm (required), period (required), numberOfPeriods (required), relatedSearchTerms.

get_shipmentGet Shipment DetailsA

Read-only

Get detailed information about a specific shipment including items, transport/tracking info, and shipping details.

Inputs: shipmentId (required).

get_shipping_labelGet Shipping LabelA

Read-only

Download a shipping label by its ID. Returns the label data (PDF).

Inputs: shippingLabelId (required).

get_signature_keysGet Signature KeysA

Read-only

Get the public keys used for webhook signature validation. Use these to verify that incoming webhook notifications are from bol.com.

Inputs: no named parameters.

get_subscriptionGet Subscription DetailsA

Read-only

Get detailed information about a specific event subscription.

Inputs: subscriptionId (required).

get_unpublished_offer_reportGet Unpublished Offer ReportA

Read-only

Retrieve an unpublished offer report by report ID. Contains all unpublished offers and reasons.

Inputs: reportId (required).

get_upload_reportGet Upload ReportA

Read-only

Get a product content upload report by upload ID. Shows the status and any validation errors for a content upload.

Inputs: uploadId (required).

handle_returnHandle ReturnA

Idempotent

Handle/process a return item by its RMA ID. The RMA ID can be found in the return items from get_return. Set the handling result and quantity returned. Valid handling results: RETURN_RECEIVED, EXCHANGE_PRODUCT, RETURN_DOES_NOT_MEET_CONDITIONS, REPAIR_PRODUCT, CUSTOMER_KEEPS_PRODUCT_PAID, STILL_APPROVED. Returns a process status — the return is handled asynchronously. Always review the return details with get_return before handling.

Inputs: rmaId (required), handlingResult (required), quantityReturned (required).

list_invoicesList InvoicesA

Read-only

List invoices from bol.com. Optionally filter by date range using period start and end dates (format: YYYY-MM-DD). The date range must not exceed 31 days.

Inputs: periodStartDate, periodEndDate.

list_ordersList OrdersA

Read-only

List recent orders from bol.com. Returns orders with their items, shipping details, and status. Use the fulfilmentMethod filter to show only FBR (fulfilled by retailer), FBB (fulfilled by bol.com), or ALL orders. Use the status filter to show OPEN (awaiting shipment/cancellation), SHIPPED, or ALL orders.

Inputs: page, fulfilmentMethod, status, changeIntervalMinute, +2 more.

list_promotionsList PromotionsA

Read-only

List available promotions on bol.com. Filter by promotion type: AWARENESS (visibility promotions) or PRICE_OFF (discount promotions).

Inputs: promotionType (required), page.

list_replenishmentsList FBB ReplenishmentsC

Read-only

List FBB (Fulfilled by bol.com) replenishments. Optionally filter by reference, EAN, date range, or state.

Inputs: page, reference, ean, startDate, +2 more.

list_returnsList ReturnsA

Read-only

List returns from bol.com. Filter by handled status and fulfilment method. Unhandled returns require action — use handle_return to process them.

Inputs: page, handled, fulfilmentMethod.

list_shipmentsList ShipmentsA

Read-only

List shipments from bol.com. Optionally filter by order ID to see shipments for a specific order.

Inputs: page, orderId, fulfilmentMethod.

list_subscriptionsList SubscriptionsA

Read-only

List all event subscriptions. Shows configured webhooks, GCP Pub/Sub, and AWS SQS subscriptions.

Inputs: no named parameters.

request_offer_exportRequest Offer ExportA

Request an offer export file containing all offers. Returns a process status — use get_process_status to get the report ID, then retrieve with get_offer_export.

Inputs: format.

request_product_destinationsRequest Product DestinationsA

Request product warehouse destinations for the given EANs. Returns a process status — use the product destinations ID to retrieve results with get_product_destinations.

Inputs: eans (required).

request_product_labelsRequest Product LabelsA

Read-only

Request product labels for FBB products. Returns label data (PDF). Specify the label format and products with EAN and quantity.

Inputs: labelFormat (required), products (required).

request_unpublished_offer_reportRequest Unpublished Offer ReportA

Request a report of all unpublished offers and reasons. Returns a process status — use get_process_status to get the report ID, then retrieve with get_unpublished_offer_report.

Inputs: no named parameters.

test_subscriptionTest SubscriptionA

Idempotent

Send a test notification to a subscription endpoint. Use this to verify that your subscription is correctly configured.

Inputs: subscriptionId (required).

update_offerUpdate OfferA

Idempotent

Update an existing offer's reference, on-hold status, product title, or fulfilment settings. To update pricing or stock, use update_offer_price or update_offer_stock instead. Returns a process status — changes are applied asynchronously.

Inputs: offerId (required), fulfilment (required), reference, onHoldByRetailer, +2 more.

update_offer_priceUpdate Offer PriceA

Idempotent

Update the pricing for an existing offer. Provide bundle prices with at least one entry for quantity 1. Returns a process status — changes are applied asynchronously.

Inputs: offerId (required), pricing (required).

update_offer_stockUpdate Offer StockA

Idempotent

Update the stock level for an existing offer. Returns a process status — changes are applied asynchronously.

Inputs: offerId (required), amount (required), managedByRetailer (required).

update_replenishmentUpdate ReplenishmentA

Idempotent

Update a replenishment, for example to cancel it or update delivery info and load carriers. Returns a process status — changes are applied asynchronously.

Inputs: replenishmentId (required), state, deliveryInfo, numberOfLoadCarriers, +1 more.

update_subscriptionUpdate SubscriptionA

Idempotent

Update an existing event subscription. You can change the resources, URL, type, enabled status, and identity.

Inputs: subscriptionId (required), resources (required), url (required), subscriptionType (required), +2 more.

update_transportUpdate TransportA

Idempotent

Update transport/tracking information for a shipment. Provide a track and trace code and optionally a transporter code. Returns a process status — the update is applied asynchronously. Use get_process_status to check completion.

Inputs: transportId (required), trackAndTrace (required), transporterCode.

upload_shipment_invoiceUpload Shipment InvoiceA

Upload an invoice for a specific shipment. Provide the shipment ID and the invoice content. Returns a process status — the upload is processed asynchronously.

Inputs: shipmentId (required), invoice (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.5/5.0

Scored 2026-05-26 10:45 across 76 tools

Disambiguation5/5

Each tool targets a distinct resource and action (e.g., get_commission vs get_commission_rates vs get_bulk_commissions). Descriptions are specific and clarify boundaries, making it easy for an agent to select the correct tool.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern using snake_case (e.g., create_offer, get_order, list_returns). Even longer names like get_process_status_by_entity adhere to this pattern. No mixing of conventions.

Tool Count2/5

76 tools is very high for a single server. While the domain is broad (bol.com marketplace), the number exceeds typical scoping. Many tools could be consolidated or are too fine-grained, making the set overwhelming.

Completeness4/5

The tool set covers the main seller workflows: offers, orders, shipments, returns, replenishments, invoices, promotions, and product content. Minor gaps exist (e.g., no direct messaging), but core operations are well-supported.

Maintenance

ActivityMaintained

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

Backlane
com.getbacklane
Hosted MCP server for OTTO Market, Kaufland and Mirakl sellers: orders, stock, listings and ads.
E-commerce & Retail Marketing Workplace & Productivity
1
https://app.getbacklane.com/mcp
kvk-handelsregister
com.iwebdevelopment
KVK Handelsregister AI Connect: hosted MCP server for the Dutch business register.
Government Data Search
1
https://mcp-kvk.iwebdevelopment.com
agentic-commerceA
io.bosonprotocol
MCP server for Boson Protocol — on-chain agentic commerce for physical & digital goods.
Blockchain E-commerce & Retail Autonomous Agents
632
https://mcp.bosonprotocol.io/mcp
mcp
com.api2cart
Unified MCP server for 70+ eCommerce platforms: products, orders, customers, and more.
E-commerce & Retail CRM
1
https://mcp.api2cart.com/

Related MCP Servers

GoDaddy Orders MCP Server
API Testing App Automation
ag2-mcp-servers
F
license
Not graded
quality
D
maintenance
MCP Server that enables interaction with GoDaddy's Orders API using natural language, auto-generated from the OTE GoDaddy Orders OpenAPI specification.
Updated a year ago (2025-07-16 14:22 UTC)
-
wefact-mcp
Payments & Billing Finance CRM
NickAldewereld
A
license
B
quality
B
maintenance
Enables natural language interaction with the WeFact invoicing platform, allowing users to manage debtors, invoices, products, subscriptions, and perform various administrative tasks via MCP-compatible clients.
Updated 5 days ago (2026-11-06 19:01 UTC)
18
1
AGPL 3.0
Steuerboard TypeScript MCPofficial
Finance
steuerboard
F
license
Not graded
quality
C
maintenance
MCP server for the Steuerboard API, enabling interaction with Steuerboard services through natural language.
Updated 2 days ago (2026-11-10 00:10 UTC)
28 npm
1
-
mcp-shopify
E-commerce & Retail CRM
cloud9-labs
A
license
C
quality
D
maintenance
MCP server for Shopify Admin API. Enables product, order, customer, and inventory management via natural language.
Updated 9 months ago (2026-02-12 04:51 UTC)
14
8 npm
1
MIT

bol-mcp

Snel starten

Quick Start (Non-Developers)

Add To Claude Desktop (Also Works In Cowork)

Add To Other AI Apps

Troubleshooting

API Coverage

Features

Supported Clients

Claude Ecosystem Notes

Setup (Power Users)

Generic MCP Server Config

Claude Code

Codex CLI (OpenAI)

Gemini CLI (Google)

VS Code (Copilot)

Claude Desktop + Cowork / Cursor / Windsurf / Cline / Zed

Docker

Other MCP Clients

Terminology

Security Notes

Configuration

Required

Optional

Authentication

Creating Your Credentials

How It Works

Security Best Practices

Available Tools

Orders

Offers

Shipments

Returns

Invoices

Commissions

Products

Product Content

Insights

Inventory

Promotions

Replenishments

Retailers

Shipping Labels

Subscriptions

Transports

Process Status

Toolset Filtering

Voorbeelden

Example Usage

Community

Development

Project Structure

Requirements

License

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

GoDaddy Orders MCP Server

wefact-mcp

Steuerboard TypeScript MCPofficial

mcp-shopify