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)

3. Voeg de server toe als MCP server in je AI-app (kopieer onderstaande configuratie)

4. Stel vragen in gewoon Nederlands (zie 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)

3. Add the server to your AI app as an MCP server (copy/paste config below)

4. 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.

1. Open your Claude Desktop MCP config file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\\Claude\\claude_desktop_config.json

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

3. 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.

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.

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:

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.

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

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

Optional

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. 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

Offers

Shipments

Returns

Invoices

Commissions

Products

Product Content

Insights

Inventory

Promotions

Replenishments

Retailers

Shipping Labels

Subscriptions

Transports

Process Status

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

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.