Bol Mcp

bol-mcp

[](https://www.npmjs.com/package/bol-mcp) [](https://opensource.org/licenses/MIT) [](https://nodejs.org/) [](https://modelcontextprotocol.io) [](https://github.com/bartwaardenburg/bol-mcp/actions/workflows/ci.yml) [](https://bartwaardenburg.github.io/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.

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

Quick Start (Non-Developers)

You do not need to clone this repo.

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

Add To Claude Desktop (Also Works In Cowork)

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

1. Open your Claude Desktop MCP config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\\Claude\\claude_desktop_config.json

1. 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"
      }
    }
  }
}

1. 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):

{
  "": {
    "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

Advanced setup and supported clients (expand)

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](#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](#configuration))

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

{
  "": {
    "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](#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](#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](#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

1. Log in to the bol.com Seller Dashboard
2. Navigate to Settings > Services > API Settings
3. Provide technical contact details (required before creating credentials)
4. Create a new API credential set
5. 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](#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 | Ca

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: BartWaardenburg
• Source: BartWaardenburg/bol-mcp
• License: MIT
• Homepage: https://github.com/BartWaardenburg/bol-mcp#readme

Install and usage instructions live in the source repository linked above.