bol MCP

bol-mcp

](https://www.npmjs.com/package/bol-mcp)  ](https://nodejs.org/)   

一个 模型上下文协议 （MCP）服务器 bol.com零售商API管理订单、报价、运输、退货、发票和佣金，所有这些都是通过人工智能应用程序中的自然语言进行的。

让我们来： 这是一个非官方的，由社区维护的项目，不与bol.com相关或批准。

社区建设 模型上下文协议 （MCP）服务器 bol.com零售商API.管理订单、报价、发货、退货、发票和佣金——所有这些都可以通过任何兼容MCP的AI客户端通过自然语言完成。

注： 这是一个非官方的、由社区维护的项目，不隶属于bol.com或得到其认可。

快速启动

你不需要克隆这个仓库。

1. 确保安装了 Node.js 20+（您的 AI 应用程序正在运行） npx op-je机器）
2. 获取bol.com API数据（见 认证)
3. 将服务器添加为 AI 应用程序中的 MCP 服务器（复制下面的配置）
4. 用简单的荷兰语提问（见 例子)

快速入门（非开发人员）

您不需要克隆此仓库。

1. 确保已安装Node.js 20+（您的AI应用程序将运行 npx 在您的机器上）
2. 获取bol.com API凭据（请参阅 认证)
3. 将服务器作为MCP服务器添加到您的AI应用程序中（复制/粘贴下面的配置）
4. 用通俗易懂的语言提问（见 示例用法)

添加到Claude桌面（也适用于协作）

Cowork在Claude Desktop内部运行，并使用相同的连接MCP服务器和权限。

1. 打开您的Claude Desktop MCP配置文件：

- macOS： ~/Library/Application Support/Claude/claude_desktop_config.json - 窗户： %APPDATA%\\Claude\\claude_desktop_config.json

1. 添加此服务器条目（或将其合并到现有的 mcpServers):

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

1. 重新启动克劳德桌面

添加到其他AI应用程序

大多数MCP应用程序都有一个类似“添加MCP服务器”的屏幕，您可以在其中填写：

• 命令： npx
• Args： -y bol-mcp
• 环境： BOL_CLIENT_ID=your-client-id 和 BOL_CLIENT_SECRET=your-client-secret

如果你的应用程序需要JSON，粘贴它并将顶级键名调整到你的客户端（常见的是 mcpServers, servers，或 context_servers):

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

故障排除

• 错误： Missing required env vars: BOL_CLIENT_ID, BOL_CLIENT_SECRET

- 修复：将两个env变量添加到MCP服务器配置中，然后重新启动应用程序。

• 错误： npx: command not found 或服务器无法启动

- 修复：安装Node.js 20+并重新启动应用程序。

• 您可以连接，但API调用失败 401/403

- 修复：在bol.com卖家仪表板中验证客户端ID/密钥是否正确且处于活动状态。

API覆盖范围

bol.com为不同目的公开了几个API。此MCP服务器涵盖 零售商API v10 和那个 共享API --市场卖家管理日常运营的核心API。

此MCP中包含的零售商API v10提供的端点功能齐全。Offer API v11是一个更新的版本，具有更新的端点结构-可能会在未来的版本中添加支持。

特性

• 76工具 包括bol.com零售商API v10在内的17个类别
• 订单管理 --通过状态和履行过滤列出、检查和取消订单
• 提供CRUD --使用价格/库存管理和导出报告创建、更新、删除报价
• 装运处理 --创建具有部分数量支持和发票请求的装运
• 退货处理 --列出、检查、创建和处理退货
• 发票访问 --按期间检索发票，包括完整的UBL详细信息和规格
• 佣金计算器 --按EAN、条件和价格计算的单笔和批量佣金率
• 产品目录 --浏览类别、搜索产品、查看竞争对手的报价、评级和资产
• 产品内容 --管理目录内容、上传报告和块推荐
• 洞察 --提供访问量、购买框百分比、绩效指标、产品排名、销售预测和搜索词
• 库存 --带过滤的LVB/FBB库存水平
• 促销 --列出并检查促销活动及其产品
• 补充资金 --完整的FBB补货生命周期：创建、更新、交货日期、取货槽、标签
• 零售商 --零售商账户信息
• 运输标签 --交付选项和标签创建
• 订阅 --带有签名密钥管理的webhook/pubsub/SQS事件订阅
• 运输 --更新运输跟踪信息
• 进程状态 --按ID、实体或批量跟踪异步操作
• OAuth2身份验证 具有自动令牌刷新功能
• 输入验证 通过每个工具上的Zod模式实现安全、可预测的操作
• 响应缓存 具有可配置的TTL和写入时自动失效功能
• 费率限制处理 具有指数回退和 Retry-After 标头支持
• 工具集过滤 仅公开所需的工具类别
• Docker支持 用于集装箱化部署
• 可操作的错误消息 具有上下文感知的恢复建议

支持的客户

Advanced setup and supported clients (expand)

此MCP服务器未绑定到一个编码代理。它适用于任何可以启动stdio MCP服务器的MCP兼容客户端或代理运行时。

克劳德生态系统笔记

Claude目前有多个易于混淆的MCP相关概念：

• 本地MCP服务器（克劳德桌面）： 定义于 claude_desktop_config.json 然后在你的机器上开始(文档).
• 合作： 重用Claude Desktop中连接的MCP服务器(文档).
• 连接器： 在Claude中管理远程MCP集成(文档).
• 协作插件： Claude特定的工作流打包（说明+工具/数据集成）(文档).在Claude中很有用，但不能作为其他代理客户端的通用MCP服务器配置进行移植。

根据供应商文件验证 2026-03-05.

设置（高级用户）

如果快速入门在您的客户中有效，您可以跳过此部分。这些是额外的每个客户端设置选项和CLI单行程序。

通用MCP服务器配置

在任何主机中使用此作为基线：

• 命令： npx
• Args： ["-y", "bol-mcp"]
• 必需的环境变量： BOL_CLIENT_ID, BOL_CLIENT_SECRET
• 可选环境变量： BOL_CACHE_TTL, BOL_MAX_RETRIES, BOL_TOOLSETS （参见 配置)

最小JSON（使顶级密钥适应您的主机）：

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

主机密钥映射：

克劳德代码

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 备选方案：

[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（谷歌）

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

集 BOL_CLIENT_ID 和 BOL_CLIENT_SECRET 在 ~/.gemini/settings.json.

VS代码（副本）

打开命令选项板(Cmd+Shift+P / Ctrl+Shift+P) > MCP: Add Server > 命令（stdio），或使用 .vscode/mcp.json 使用顶级密钥 servers 以及来自的规范命令/args/env块 通用MCP服务器配置.

克劳德桌面+协作/光标/风帆/克莱恩/泽德

Cowork在Claude Desktop内部运行，并使用相同的连接MCP服务器和权限。在Claude Desktop中配置一次，服务器就可以在Cowork中使用。

使用规范配置块，并将其与匹配的顶级密钥一起放置在下面的主机文件中。

码头工人

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

其他MCP客户端

使用以下值 通用MCP服务器配置.

术语

什么是可跨主机移植的：

• MCP服务器运行时设置(command, args, env)
• 运输模型(stdio 命令服务器）
• 此服务器公开的工具名称和工具模式

什么是特定于主机/供应商的（不可移植）：

• 主机配置密钥名称(servers, mcpServers, context_servers, mcp_servers)
• 主机UX/添加服务器的工作流（CLI命令、UI菜单、设置路径）
• 人类特有的概念，如 Claude Desktop本地MCP服务器, Claude连接器通过远程MCP，以及 Claude代码插件 用于联合工作流程

安全说明

• 信任模型： 允许调用此MCP服务器的任何提示或代理都可以使用配置的凭据执行bol.com API操作。
• 最低权限凭据： 每个环境/团队/用例使用单独的bol.com API凭据，并在访问更改时轮换/撤销。
• 书面行动批准： 为变异工具启用主机端审批(create_*, update_*, delete_*, cancel_*, handle_return装运/补货行动）。
• 团队配置治理： 将共享MCP配置保留在版本控制中，要求检查命令/args/env/toolset过滤的更改，并将机密保存在vault或主机机密管理器中（而不是纯文本仓库文件中）。

配置

必需的

在中生成您的凭据 bol.com合作伙伴平台 在...之下 设置>API设置.

可选的

认证

此服务器使用 OAuth2客户端凭据流。它会自动获取和刷新访问令牌——您只需提供客户端ID和密码。

有关完整详细信息，请参阅 官方bol.com身份验证文档.

创建您的凭据

1. 登录到 bol.com卖家仪表板
2. 导航至 设置 > 服务 > API设置
3. 提供技术联系方式（创建凭据前需要）
4. 创建新的API凭据集
5. 复制 客户端ID 和 客户端密钥

运作原理

服务器通过bol.com令牌端点将您的凭据交换为短期访问令牌：

• 端点： POST https://login.bol.com/token
• 认证： HTTP基础版 base64(clientId:clientSecret)
• 资助类型： client_credentials
• 令牌寿命： 约5分钟（299秒）

令牌在到期前会自动重用和刷新，不需要手动令牌管理。

安全最佳实践

看 安全说明.bol.com特定的证书卫生：

• 切勿共享您的客户端ID或客户端机密，也不要在源文件中硬编码它们
• 使用环境变量或主机密钥存储传递凭据
• 如果怀疑存在泄露，请立即撤销并替换凭据

可用工具

订单

优惠

货运

退货

发票

佣金

产品

产品内容

洞察

库存

促销

补充资金

零售商

运输标签

订阅

运输

进程状态

工具集筛选

通过仅启用所需的工具类别来减少上下文窗口的使用。设置 BOL_TOOLSETS 将环境变量转换为逗号分隔的列表：

BOL_TOOLSETS=orders,offers

如果未设置，则启用所有工具集。无效名称将被忽略；如果所有名称都无效，则启用所有工具集作为回退。

例子

一旦连接，您可以用简单的荷兰语提问：

• “显示我的所有未决订单”
• “输入订单详情 1234567890”
• “报价 EAN 9781234567890 价格 19,99 EUR 有库存 50 件”
• “将库存更新为报价 abc-123 至 25 件”
• “使用TNT运输代码发送订单项目1234567890”
• “显示所有未处理的回报”
• “EAN 9781234567890的佣金为29.99欧元？”
• “显示我的2025年1月发票”

示例用法

连接后，您可以使用自然语言与bol.com API进行交互：

• “列出我的所有未结订单”
• “显示订单1234567890的详细信息”
• “以19.99欧元的价格为EAN 9781234567890创建报价，有50件库存”
• “将报价库存abc-123更新为25个单位”
• “运送订单1234567890中的订单项目，运输代码TNT”
• “显示所有未处理的退货”
• “29.99欧元的EAN 9781234567890的佣金是多少？”
• “列出我2025年1月的发票”

社区

• 技术支持： 支持.md
• 安全报告： 安全.md
• 贡献指南： 贡献.md
• Bug报告和功能请求： 问题

发展

# Install dependencies
pnpm install

# Run in development mode
pnpm dev

# Build for production
pnpm build

# Run tests
pnpm test

# Type check
pnpm typecheck

项目结构

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

需求

• Node.js>=20
• A. bol.com 网站 具有API证书的卖家帐户

许可证

麻省理工学院-见 许可证 了解详情。