Albert Heijn

albert-heijn-be-mcp

非官方项目，与 Albert Heijn 或 Ahold Delhaize 无关。基于 olekpuchka/albert-heijn-mcp v1.7.1，为 ah.be 提供服务，无需登录。

面向 Albert Heijn Belgium（ah.be）的 MCP 服务。无需账户：使用 --anonymous 时，它会提供七个只读工具（商品、本周优惠、优惠分组、商品替代品、食谱），不会执行任何涉及登录、清单或订单的操作。它基于 olekpuchka/albert-heijn-mcp v1.7.1 的代码（参见 NOTICE），且不跟随上游项目更新。v1 不支持比利时登录。下方附有上游项目的 README，适用于 ah.nl，且需要登录。

Claude Desktop（.mcpb）：从发布页面下载 albert-heijn-be-mcp.mcpb，然后双击文件；也可以前往 Settings → Extensions → Advanced settings → Install Extension… 并选择该文件。它无需登录即可启动（匿名模式），包含所需的一切，也不需要令牌。

docker run（在端口 3000 上使用 Streamable HTTP，AH_SITE=be，匿名模式）。此镜像无需令牌：

docker run --rm --read-only -p 127.0.0.1:3000:3000 ghcr.io/arnouthoebreckx/albert-heijn-be-mcp

MCP 端点为 http://127.0.0.1:3000/mcp；GET /healthz 会返回 ok。此服务不会验证调用方身份，因此只能在私有网络中通过网关对外提供。

LiteLLM：将此容器添加到代理的 config.yaml。之后，Agent 可通过 ah_be-<tool> 调用这些工具，例如 ah_be-ah_search_products。

mcp_servers:
  ah_be:
    url: "http://albert-heijn-be-mcp:3000/mcp"
    transport: "http"

npx（stdio）：每次从 GitHub 的 npm 注册表安装软件包时（包括公开软件包），都需要令牌。镜像和 .mcpb 无需令牌。先将以下两行添加到 ~/.npmrc（该令牌是带有 read:packages 范围的经典 GitHub 令牌）：

@arnouthoebreckx:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=<a classic GitHub token with read:packages>

然后运行它。需要 Node.js 24：

npx -y @arnouthoebreckx/albert-heijn-be-mcp --anonymous

若要改为从桌面应用启动，请将以下内容添加到应用的 MCP 设置中，例如 claude_desktop_config.json（Settings → Developer → Edit Config）：

{
  "mcpServers": {
    "ah-be": {
      "command": "npx",
      "args": ["-y", "@arnouthoebreckx/albert-heijn-be-mcp", "--anonymous"]
    }
  }
}

---

albert-heijn-mcp

在 AI 助手中使用你的 Albert Heijn 账户。

将你的 Albert Heijn 账户连接到 Claude、ChatGPT 或 Cursor 等 AI 助手，只需提问即可购买杂货。查找商品和优惠，使用 Allerhande 食谱规划餐食，更新购物清单和配送订单，并回顾你买过的商品。

从技术角度来说，这是一个面向 Albert Heijn 🇳🇱 的 Model Context Protocol（MCP）服务。MCP 是 AI 应用连接其他服务的标准，因此它适用于任何支持 MCP 的应用。

说明

这是一个非官方项目，与 Albert Heijn 无关，也未获其认可。它使用与 AH 手机应用相同的 API，该 API 可能会在不另行通知的情况下更改。

---

目录

面向所有人

• 你可以提出的请求
• 快速入门：先连接应用，再登录
• 故障排查

技术细节

• 通过 HTTP 使用匿名模式，以及 Docker 镜像
• 在服务上运行，供 ChatGPT 和 Claude.ai 使用
• 配置
• 工具和限制
• 开发

你可以问什么

可以用荷兰语、英语或助手支持的任何语言提问：

“这周我平时买的东西中，哪些在打折？”

规划餐食

“找一道 Allerhande 的素食食谱，烹饪时间不超过 30 分钟，适合两人食用，并把食材加入我的购物清单。我已经有橄榄油和盐了。”

“把平底锅千层面食谱的份量调整到六人，并告诉我需要多少鲑鱼。”

“根据本周的特价商品，规划三顿工作日晚餐。”

省钱

“我平时买的哪些商品本周在打折？”

“用本周特价的食材重做今晚的炒菜，但不要对食谱做太大改动。”

“下周的特价商品清单出了吗？如果还没出，什么时候会公布？”

“2+1 免费的奶酪优惠包含哪些商品？”

购物

“把我至少订购配送过三次的商品重新加入清单。”

“按价格从低到高，查找有机无麸质意面。”

“比较这三种酸奶的蛋白质和糖含量，并把最合适的一种加入清单。”

“AH 周六什么时候可以配送？”

“西葫芦售罄了。这道食谱里还能用什么代替？”

“给我即将配送的订单再加两包牛奶。”

“创建一个名为 Pasta night 的收藏清单，加入这道食谱里的所有食材。”

“我附近的 AH 有今天到期的面包或蔬菜值得今晚去买么？”

回顾

“我 9 月的店内购物小票总金额是多少？最贵的五件商品是什么？”

“显示我上次购物的小票，并列出我买了不止一次的商品。”

开始使用

你需要一个 Albert Heijn 账户。然后：

1. 连接你的应用：从下方选择你的应用。
2. 登录 Albert Heijn：让助手帮你登录一次即可。
3. 开始提问。 查看你可以问什么。

连接客户端

你的应用	操作方法
Claude Desktop	下载并双击。最简单的方式；无需安装其他内容。
Cursor、VS Code	一键安装按钮
ChatGPT、Claude.ai（网页端和移动端）	需要你自己的服务（需要一定技术能力）
其他应用	在应用设置中添加命令

Claude Desktop

1. 下载 albert-heijn-be-mcp.mcpb。
2. 双击文件并选择 Install。如果文件没有在 Claude 中打开，请前往 Settings → Extensions → Advanced settings → Install Extension…，然后选择该文件。

完成：文件已包含所需的一切。要更新，请使用最新版本中的文件重复上述操作。

其他支持 MCP Bundles（.mcpb 文件）的桌面应用也可以用相同方式安装。

Cursor 和 VS Code

先安装 Node.js 24 (LTS)，并确保已添加本页面顶部的两行 ~/.npmrc 内容（GitHub 的 npm registry 每次安装都需要令牌），然后点击：

ChatGPT 和 Claude.ai

Web 和移动应用无法在你的计算机上运行任何内容；它们只会连接到互联网上的服务器。因此，你需要先在服务器上运行，这需要一些技术知识。然后将其添加为连接器：

• ChatGPT 需要开发者模式（Plus、Pro、Business、Enterprise 和 Education）。打开 Settings → advanced settings，启用 Developer mode，然后使用 https://your-server/mcp 创建连接器。将身份验证设为 OAuth。
• Claude.ai：Settings → Connectors → Add custom connector，粘贴 https://your-server/mcp 并选择 Connect。

随后，应用会打开你服务器上的登录页面：在其中输入 AH_MCP_TOKEN，只需一次。

其他应用

需要通过本地命令启动 MCP 服务的应用需要 Node.js 24 (LTS)，并运行 npx -y @arnouthoebreckx/albert-heijn-be-mcp，该命令会从 GitHub Packages 下载并运行最新版本；它需要本页顶部的两行 ~/.npmrc 配置。大多数应用会在 MCP 设置中使用以下 JSON：

{
  "mcpServers": {
    "ah": {
      "command": "npx",
      "args": ["-y", "@arnouthoebreckx/albert-heijn-be-mcp"]
    }
  }
}

各应用的设置位置有所不同；请参阅其文档。通常带有命令行的应用会提供添加命令，例如 <client> mcp add ah -- npx -y @arnouthoebreckx/albert-heijn-be-mcp。它也已列入 MCP Registry，部分应用会从中安装。

若要永久安装，请运行 npm install --global @arnouthoebreckx/albert-heijn-be-mcp，然后使用 albert-heijn-be-mcp 命令；再次运行同一命令即可更新。

提示

桌面应用不会加载你的 Shell 配置文件，因此可能找不到 npx（使用 nvm 时很常见）。此时请将 command 设为 which npx 的输出。

登录

比利时（--site be，默认值）： 比利时登录不属于 v1 的范围，也未经测试。登录工具指向 login.ah.be，但没人确认它们是否可用。对于 ah.be，请使用 --anonymous 运行服务（见配置）：无需登录，即可使用搜索、商品和奖励功能。

请让你的助手帮你登录 Albert Heijn。只需登录一次；之后登录状态会保留并自动续期。

在你的电脑上（Claude Desktop、Cursor、VS Code 及其他本地应用），系统会打开一个单独的浏览器窗口，显示 AH 的登录页面。像平常一样在其中登录：窗口会自动关闭，之后你就已登录。然后告诉你的助手你已完成。

此窗口使用全新、空白的浏览器配置，因此需要手动输入密码：这里无法使用已保存的密码和密码管理器扩展。需要使用 Chrome、Edge、Brave 或 Chromium（Ubuntu 上不能使用 snap 版本），并且需要屏幕；否则请按下文所述手动复制代码。

在服务器上（ChatGPT、Claude.ai），或者无法打开登录窗口时，你需要手动复制代码。AH 的登录页面有一个只能在 AH 自己的网站上使用的验证码，因此代码必须从你的浏览器中获取：

你需要用电脑操作，不能用手机或平板：它们的浏览器没有开发者控制台。Chrome、Edge 或 Brave 效果最好。

1. 打开助手发给你的链接，但先不要登录。

2. 在该标签页中打开开发者控制台，这是一个可安全打开的 Web 开发者面板：Mac 上按 ⌘ ⌥ J，Windows 和 Linux 上按 Ctrl Shift J。

3. 登录，像平常一样操作。随后 AH 会尝试打开它的手机应用，但浏览器无法执行此操作，因此页面看起来像是卡住了。在控制台中找到这行红色文字：

   Failed to launch 'appie://login-exit?code=…' because the scheme does not have a registered handler.
   

4. 复制从 appie:// 到结束引号之间的内容，并粘贴到聊天中。此代码只能使用一次，且很快就会过期，因此请立即粘贴。

没有看到这一行？请参阅故障排除。如需在没有开发者控制台的情况下登录服务器，请参阅在服务器上运行。

登录信息的存储位置

登录信息会保存在你自己的电脑上，并自动续期。该文件只有你的用户可以读取：

操作系统	位置
macOS	~/Library/Application Support/albert-heijn-mcp/tokens.json
Linux	~/.config/albert-heijn-mcp/tokens.json（或 $XDG_CONFIG_HOME 下）
Windows	%AppData%\albert-heijn-mcp\tokens.json

使用 AH_TOKENS_PATH 覆盖该位置。

## 故障排查

没有打开登录窗口

登录窗口需要在常规位置安装 Chrome、Edge、Brave 或 Chromium，并且需要有屏幕：不能通过 SSH 使用，也不能使用 Ubuntu 的 snap Chromium。没有这些条件时，助手会改为提供链接，你可以手动复制代码。如果窗口在你完成操作前关闭，请重新登录。

登录后没有出现“Failed to launch”行

必须先打开开发者控制台，再登录。打开控制台，然后在同一个标签页中再次打开登录链接并登录。如果你仍处于登录状态，AH 跳过了登录表单，也没关系：该行仍会照常出现。你也可以在 Network 标签页中查找 appie://login-exit?code=… 请求。Chrome、Edge 或 Brave 以外的浏览器可能会改为在错误页面或对话框中显示链接。

登录时出现“exchange code”错误

代码只能使用一次，并且会很快过期。请重新登录，并立即粘贴新链接。

出现“Not logged in”，或会话似乎已损坏

请让助手先退出登录，再重新登录；或者从登录位置删除 tokens.json，然后重新登录。

出现“The Albert Heijn login has expired”

Albert Heijn 不再接受已存储的登录信息。请让助手重新登录 Albert Heijn。将应用重新连接到服务并无帮助：那是单独的登录操作。

如果登录信息在你的服务上持续过期，请将 tokens.json 存放在重启和重新部署后仍会保留的存储空间中，并且只运行一个实例。AH 每次续期都会替换登录信息，因此旧版文件副本或自行续期的第二个实例都会被拒绝。

粘贴登录代码时出现“Already connected as …”

代码不会替换有效的登录信息，因此别人的账户代码无法切换你的账户。要切换账户，请先退出登录，然后再重新登录。

出现“There is no active delivery order to change”

AH 仅在订单创建后才接受订单变更。请先在 AH 应用或 ah.nl 上选择配送时段。

出现“The shopping list is not available while a delivery order is active”

选择时段后，购物清单已移入订单。在订单送达或取消之前，请让助手修改订单（使用 ah_get_cart、ah_update_cart_item）。

服务无法启动：“needs AH_MCP_TOKEN of at least 32 characters”

将 AH_MCP_TOKEN 设为较长的随机值，例如 openssl rand -hex 32 的输出，然后重启。更改该值会使所有客户端退出登录；重新连接一次即可。

服务登录页面显示“This login link is not valid”

请从应用重新开始连接。如果输入令牌后仍立即出现此问题，请检查 AH_MCP_BASE_URL 是否与浏览器中的地址完全一致，包括 https://：登录表单只接受来自该地址的请求。

服务登录页面在 localhost 打开，或应用无法连接到服务

将 AH_MCP_BASE_URL 设为服务的公开 https:// URL，然后重启服务。应用会被发送到该地址进行登录。

端口 3000 已被占用

在环境变量或 .env 中将 AH_MCP_PORT 设为其他端口。

---

通过 HTTP 使用匿名模式，以及 Docker 镜像

使用 --anonymous 时，服务不需要 Albert Heijn 账户，并且只注册无需账户即可使用的工具：ah_search_products、ah_get_products、ah_get_bonus_offers、ah_get_bonus_group_products、ah_get_product_alternatives、ah_search_recipes 和 ah_get_recipe。ah_get_bonus_offers 使用 previously_bought: true 时需要账户，因此会返回错误。

通过 Streamable HTTP 使用匿名模式时，不需要 OAuth，也不需要 AH_MCP_TOKEN：无人登录，也不涉及任何账户或个人数据。服务在 AH_MCP_HOST（默认值为 127.0.0.1）和 AH_MCP_PORT（默认值为 3000）上提供 /mcp，并提供 GET /healthz，该端点返回 200 和 ok：

npx -y @arnouthoebreckx/albert-heijn-be-mcp --transport streamable-http --anonymous

警告

此模式下不会对调用方进行身份验证。只能在网关后面的私有网络中暴露此服务（例如 LiteLLM，或负责身份验证的反向代理），绝不要直接暴露到互联网。

Docker 镜像以此模式启动：AH_SITE=be、--anonymous、Streamable HTTP，并监听 0.0.0.0:3000。它以非 root 用户运行，不会向磁盘写入任何内容，不保存任何密钥，并在 /healthz 上配置了健康检查：

docker build -t albert-heijn-be-mcp .
docker run --rm --read-only -p 127.0.0.1:3000:3000 albert-heijn-be-mcp

不使用 --anonymous 时，Streamable HTTP 会使用上游模式，仍需要 AH_MCP_TOKEN，详见下文。

---

在服务器上运行

ChatGPT 和 Claude.ai 等 Web 和移动应用需要通过 HTTPS 和 Streamable HTTP 访问互联网上的服务。端点为 https://your-server/mcp。

应用通过 OAuth 登录：使用 OAuth（或自动）身份验证添加端点后，应用会打开服务器上的登录页面。在该页面输入一次 AH_MCP_TOKEN；之后，应用会获取自己的令牌并自动续期。服务器只接受这些 OAuth 令牌，不接受 AH_MCP_TOKEN 本身，因此不支持 OAuth 的应用无法通过 HTTP 连接；请改为在本地运行。

重要

任何持有 AH_MCP_TOKEN 的人都能登录并使用你的 Albert Heijn 账户。请使用较长的随机值（openssl rand -hex 32）。更改此值会让所有客户端退出登录。

服务通过反向代理运行，采用经过强化的 systemd 服务，并从 GitHub Packages 安装；安装需要令牌（本页顶部的两行 ~/.npmrc 配置，适用于运行 npm install 的用户）：

1. 准备服务器。 安装 Node.js 24 并创建服务用户：

   sudo useradd -r -m -d /home/albert-heijn-be-mcp -s /sbin/nologin albert-heijn-be-mcp
   

2. 在 /home/albert-heijn-be-mcp/.env 中配置服务：

   AH_MCP_BASE_URL=https://albert-heijn-be-mcp.example.com
   AH_MCP_TOKEN=<output of: openssl rand -hex 32>
   

   将文件权限设置为仅服务用户可读：sudo chown albert-heijn-be-mcp: /home/albert-heijn-be-mcp/.env && sudo chmod 600 /home/albert-heijn-be-mcp/.env。

3. 使用随软件包提供的服务单元安装服务（该服务以 --remote 模式运行）：

   sudo npm install --global --prefix /usr/local --ignore-scripts @arnouthoebreckx/albert-heijn-be-mcp
   sudo install -m 644 /usr/local/lib/node_modules/@arnouthoebreckx/albert-heijn-be-mcp/deploy/albert-heijn-be-mcp.service /etc/systemd/system/
   sudo systemctl daemon-reload
   sudo systemctl enable --now albert-heijn-be-mcp
   

   要更新，请运行相同的命令，然后运行 sudo systemctl restart albert-heijn-be-mcp。

4. 使用反向代理添加 TLS，并将请求转发到 127.0.0.1:3000。使用 Caddy 时：

   albert-heijn-be-mcp.example.com {
       reverse_proxy 127.0.0.1:3000
   }
   

要让服务器登录 Albert Heijn，请让已连接的应用为你登录，然后手动复制代码。也可以跳过代码：在自己的电脑上通过登录窗口登录，然后将登录凭据复制到服务器：

AH_TOKENS_PATH=./server-tokens.json npx -y @arnouthoebreckx/albert-heijn-be-mcp login
scp server-tokens.json your-server:ah-tokens.json && rm server-tokens.json
ssh -t your-server 'sudo sh -c "install -d -o albert-heijn-be-mcp -g albert-heijn-be-mcp -m 700 /home/albert-heijn-be-mcp/.config/albert-heijn-mcp && install -o albert-heijn-be-mcp -g albert-heijn-be-mcp -m 600 $HOME/ah-tokens.json /home/albert-heijn-be-mcp/.config/albert-heijn-mcp/tokens.json.new && mv /home/albert-heijn-be-mcp/.config/albert-heijn-mcp/tokens.json.new /home/albert-heijn-be-mcp/.config/albert-heijn-mcp/tokens.json && rm $HOME/ah-tokens.json"'

服务器会在下一次请求时读取该文件；无需重启。单独的文件可将电脑上的登录凭据与服务器上的分开保存：AH 每次续期时都会替换登录凭据，因此每个登录凭据只能在一个位置使用。如果主机无法通过 SSH 访问，请将文件上传到服务器存放登录凭据的位置：AH_TOKENS_PATH，或该服务运行用户的默认位置。

服务只能写入 /home/albert-heijn-be-mcp，令牌保存在该目录中。如果将 AH_LOG_FILE 指向其他位置，请在单元文件的 ReadWritePaths 中添加该路径。

配置

设置项为环境变量。也可以将它们写入工作目录中的 .env 文件（参见 .env.example）；已设置的环境变量优先级更高。在托管平台上，请在其环境变量或密钥设置中设置这些变量，而不要使用 .env 文件，以免 AH_MCP_TOKEN 留在应用文件中。

变量	默认值	描述
AH_SITE	be	Albert Heijn 站点：be（ah.be）或 nl（ah.nl，即上游站点）。与 --site 相同。商品、菜谱和优惠链接会指向 www.ah.be 或 www.ah.nl。
AH_ANONYMOUS	false	true：无需登录。服务会从 Albert Heijn 获取匿名令牌（保存在内存中，不生成令牌文件），并将其用于无需账户的调用。与 --anonymous 相同。
AH_API_BASE_URL	按站点而定	替换 API 主机（https://api.ah.be 或 https://api.ah.nl）。仅用于测试。
AH_REMOTE	false	登录时不打开浏览器，而是通过复制验证码登录（与 --remote 相同）。使用 streamable-http 时始终启用。
AH_TOKENS_PATH	按操作系统而定	登录令牌的存储位置。
AH_MCP_HOST	127.0.0.1	HTTP 服务监听的接口。若位于反向代理之后，请保留默认值。
AH_MCP_PORT	3000	HTTP 服务端口。
AH_MCP_BASE_URL	http://localhost:3000	HTTP 服务的公开 URL。在服务器上设置此项：OAuth 客户端会跳转到此 URL 登录；对于非本地 URL，还会关闭仅限 localhost 的 Host 检查，以便反向代理转发请求。
AH_MCP_TOKEN	—	HTTP 传输的密钥，至少 32 个字符；未设置此项时传输不会启动，--anonymous 除外。登录时需在 OAuth 登录页面输入此密钥；它也用于签署 OAuth 令牌。
AH_LOG_FILE	—	同时将日志追加到此文件。日志始终写入 stderr。

命令行标志：

node dist/index.js [--site be|nl] [--anonymous] [--transport stdio|streamable-http] [--remote] [--version] [--help]
node dist/index.js login [--remote]

stdio（默认）供本地客户端使用；streamable-http 在 /mcp 提供 MCP 服务，并在 /authorize 提供 OAuth 登录（使用 --anonymous 时不启用 OAuth，且 GET /healthz 会返回 ok）。login 会在终端登录 Albert Heijn，保存令牌后退出；使用 --remote 时会要求输入验证码，而不是打开登录窗口。

工具

这些工具供助手在后台使用；你无需亲自调用。只读工具会标记为只读，因此应用可以直接运行它们，无需询问。会删除数据的工具会标记为破坏性操作，因此应用会先请求确认。

返回数据的工具还会以结构化输出形式返回数据，并声明相应的架构，供使用此功能的客户端使用。工具结果中的商品和菜谱会包含指向 ah.nl 对应页面的 url，服务会要求助手将其名称链接到该页面。

账户

工具	描述
ah_login	登录：在你的电脑上打开登录窗口，或返回 AH 的登录链接，并通过你粘贴回来的验证码完成登录。
ah_logout	删除已存储的令牌，以切换账户或重置会话。
ah_get_member_profile	姓名、已屏蔽的电子邮件地址和优惠卡号（末 4 位）。

商品与优惠

| 工具 | 描述 | |---|---| | `ah_search_products` | 一次搜索一个或多个关键词；使用荷兰语词语效果最佳。可通过 `bonus=true` 或 `filters`（有机、纯素、无麸质及其他饮食类型、过敏原和标签）筛选，并按价格、最常购买的商品或 Nutri-Score 排序。 | | `ah_get_products` | 获取一个或多个商品的详情。`include_nutritional_info=true` 会添加营养成分表。 | | `ah_get_product_alternatives` | 获取 AH 为某件商品推荐的类似商品和替代品。 | | `ah_get_bonus_offers` | 获取本周的 bonus 优惠；设置 `period=next` 可获取下周优惠。`previously_bought=true` 可将结果限制为你之前购买过的商品（AH 的“Eerder gekocht”）。可按关键词筛选。 | | `ah_get_bonus_group_products` | 获取团购优惠（如“买 2 送 1”）中包含的各个商品。 | | `ah_search_stores` | 按邮政编码或你的地址查找附近的商店。 | | `ah_get_last_chance_items` | 获取门店中的今日折扣商品；默认显示离你地址最近的门店。 |

食谱

工具	描述
ah_search_recipes	搜索 Allerhande 食谱；使用荷兰语词语效果最佳。
ah_get_recipe	获取食材、步骤和每份的营养信息。servings 可按份数调整食材用量。
ah_add_recipe_to_shopping_list	将食谱食材匹配到商品，并一步添加到清单。优先选择有 bonus 优惠的商品（设置 prefer_bonus=false 可关闭此选项）；skip 可跳过你已有的食材，dry_run=true 可预览匹配结果。

购物清单和收藏夹

工具	描述
ah_get_shopping_list	获取你的购物清单（“Mijn lijst”），即购物时填写的清单。
ah_add_to_shopping_list	将商品添加到清单，并为每件商品设置数量。
ah_add_free_text_to_shopping_list	添加自由文本商品，例如“verse bloemen”。
ah_remove_from_shopping_list	移除商品或自由文本项目。
ah_clear_shopping_list	移除所有内容。需要 confirm="yes"。
ah_get_favorite_lists	获取你的收藏清单（“Mijn lijstjes”）。
ah_add_to_favorite_list	将商品添加到收藏清单。
ah_remove_from_favorite_list	从收藏清单中移除商品。
ah_create_favorite_list	创建一个新的空收藏清单。
ah_delete_favorite_list	删除收藏清单及其中的项目。需要 confirm="yes"。

配送订单

在 AH 应用中选择配送或自取时段，会将购物清单转为订单。ah_get_delivery_slots 显示可配送的时间；其他工具则用于操作该订单。

工具	描述
ah_get_delivery_slots	获取未来几天内可配送到你地址的时间段。
ah_get_cart	获取当前订单中的商品，以及总价和折扣。
ah_update_cart_item	更改商品数量；设为 0 可将其移除。
ah_remove_from_cart	从订单中移除商品。
ah_clear_cart	移除订单中的所有内容。需要 confirm="yes"。

订单和收据

工具	描述
ah_get_orders	获取即将配送的订单；设置 past=true 可获取过去的订单。
ah_get_order_details	获取某个订单中的商品。
ah_get_frequent_items	获取你最常订购的商品，按配送订单统计。
ah_get_receipts	获取近期的店内收据（kassabonnen）。
ah_get_receipt_details	获取某张收据上的商品、折扣和付款信息。

### 限制

• 无法通过 API 发起配送订单。 ah_get_delivery_slots 会列出配送时段，但预约时段并发起订单需要在 AH 应用或 ah.nl 上完成。订单生效期间，AH 不提供购物清单；工具会说明这一点，并指向订单工具。
• 不支持勾选购物清单中的商品： API 不会返回可用的商品 ID。
• Bonus Box 是 AH 的每周个性化优惠，目前不可用：其 API 尚不明确。
• 每次调用的限制： 每种商品最多 99 件，最多 50 个商品；自由文本商品名称或清单名称最多 100 个字符。

开发

git clone https://github.com/arnouthoebreckx/albert-heijn-be-mcp
cd albert-heijn-be-mcp
npm ci
npm run build    # compile to dist/
npm run lint     # type-check

在检出目录中使用 node dist/index.js 运行；也可以在客户端配置中将 /path/to/albert-heijn-be-mcp/dist/index.js 设为参数，并将 node 设为命令。

路径	内容
src/index.ts、src/config.ts、src/loginCommand.ts	入口点、标志和设置，以及 login 命令
src/ahapi/	AH REST 和 GraphQL API 客户端，使用 Node 内置的 fetch
src/auth/	登录窗口、登录代码交换、令牌存储与刷新
src/server/	Streamable HTTP 传输和 OAuth 登录
src/tools/	MCP 工具，每个领域对应一个文件
deploy/	随软件包一同提供的 systemd 单元
manifest.json、.mcpbignore	.mcpb 捆绑包的清单，以及其中排除的文件
listing/	在连接器设置和应用目录中使用的名称、描述和图标（说明）
.github/	CI、发布工作流、Dependabot 和固定版本的 mcp-publisher 安装
assets/	此 README 的 Logo，以及 MCP 客户端显示的服务图标

运行时唯一的依赖项是官方 MCP TypeScript SDK 和 Zod，SDK 使用 Zod 定义工具架构。

若要手动调用工具，请使用 MCP Inspector：

npx @modelcontextprotocol/inspector node dist/index.js

部署更改前，请使用真实账户快速检查：登录，搜索 melk，向购物清单添加一件商品并将其移除，然后查看购物车和订单。

要发布版本，请使用 npm version 1.2.3 --no-git-tag-version 设置新版本，并在 server.json（version、.mcpb URL 和镜像标签）及 manifest.json 中更新版本；将更改合并到 main，然后推送标签：git tag v1.2.3 && git push origin v1.2.3。只有仓库管理员可以创建 v* 标签。发布工作流 会检查版本是否一致、构建软件包，将其作为 albert-heijn-be-mcp.tgz 附加到 GitHub 发布中，同时附上 albert-heijn-be-mcp.mcpb 捆绑包；它还会为 tarball 生成构建来源证明，并使用工作流自身的令牌将其发布到 GitHub Packages（不会存储 npm 令牌，也无需等待审批），同时构建多架构镜像并将其推送到 ghcr.io/arnouthoebreckx/albert-heijn-be-mcp，并附上构建来源证明。.mcpb 和镜像发布后，registry 作业会将 .mcpb 的 SHA-256 添加到 server.json 的副本中，并通过 GitHub OIDC 将 .mcpb 和镜像列入 MCP 注册表。注册表无需令牌即可拉取镜像，因此请在仓库的 Packages 下将软件包设为公开；如果首次运行失败，请重新运行该作业。发布开始时不会附带说明，请在 GitHub 上撰写说明。

许可证

Apache 2.0