Albert Heijn

本地服务

github.com生产力13 周前更新

代码仓库访问官网

关于 Albert Heijn

Albert Heijn 是连接个人 Albert Heijn 账户的非官方 MCP 服务，供购物与饮食规划使用。它涵盖商品、优惠、食谱、购物清单、配送订单和收据。

主要功能

01搜索商品与 Bonus 优惠
02查找 Allerhande 食谱并规划餐食
03管理购物清单和配送订单
04查看购买记录与收据

适用场景

01按优惠商品安排晚餐
02将食谱食材加入购物清单
03更新即将配送的订单
04汇总收据中的消费与商品

MCP 相关

该 MCP 服务向兼容客户端开放 Albert Heijn 账户相关的购物与订单功能。客户端可在本地运行服务，或通过支持 OAuth 的远程 HTTP 连接使用。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "olekpuchka-albert-heijn": {
      "command": "npx",
      "args": [
        "-y",
        "albert-heijn-mcp"
      ]
    }
  }
}

启动命令npx -y albert-heijn-mcp

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmalbert-heijn-mcp1.7.1stdio

工具

收录的工具列表 · 更新于 2 周前

参数	类型	必填	说明
code	string	否	用户登录後复制的 appie://login-exit?code=... 链接，或仅提供代码。省略则开始登录。

详细介绍

albert-heijn-mcp

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

将你的 Albert Heijn 账户连接到 Claude、ChatGPT 或 Cursor 等 AI 助手，只需提出要求即可购买食品杂货。查找商品和 Bonus 优惠，根据 Allerhande 食谱规划餐食，随时更新购物清单和配送订单，还能回顾买过的东西。

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

说明

这是一个非官方项目，与 Albert Heijn 无关联，也未获其认可。它使用与 AH 移动应用相同的 API，该 API 可能会在不另行通知的情况下发生变化。

你可以提出哪些要求

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

“这周我常买的东西有哪些特价？”

规划餐食

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

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

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

省钱

“我常买的商品中，哪些这周有特价？”

“用特价食材重新搭配今晚的炒菜，但不要大幅改动食谱。”

“下周的特价信息发布了吗？如果还没有，什么时候发布？”

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

购物

“把至少配送给我 3 次的商品重新添加到我的清单。”

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

“比较这 3 种酸奶的蛋白质和糖含量，并把最好的那种添加到我的清单。”

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

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

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

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

“今晚我附近的 AH 有值得买的今日折价面包或蔬菜吗？”

回顾消费

“我 9 月份的店内收据总额是多少？最贵的 5 件商品是什么？”

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

快速开始

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

连接你的应用：从下方选择你的应用。
登录 Albert Heijn：让助手帮你登录一次即可。
开始提问。 查看你可以提出哪些要求。

连接客户端

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

Claude Desktop

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

就是这么简单：该文件包含所需的一切。要更新，请使用最新版本中的文件重复上述步骤。

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

Cursor 和 VS Code

请先安装 Node.js 24 (LTS)，然后点击：

ChatGPT 和 Claude.ai

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

ChatGPT 需要开发者模式（Plus、Pro、Business、Enterprise 和 Education）。打开 Settings → advanced settings，启用开发者模式，然后使用 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 albert-heijn-mcp 来下载和运行最新版本。大多数应用可以在 MCP 设置中使用以下 JSON：

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

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

如果要永久安装，请运行 npm install --global albert-heijn-mcp 并使用 albert-heijn-mcp 命令；再次运行同一命令即可更新。

提示

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

打开助手提供的链接，但暂时不要登录。
在该标签页中打开开发者控制台。这是供 Web 开发者使用的面板，可以安全打开：Mac 上按 ⌘ ⌥ J，Windows 和 Linux 上按 Ctrl Shift J。
像平常一样登录。随后 AH 会尝试打开其手机应用，但你的浏览器无法执行此操作，因此页面看起来像是卡住了。在控制台中找到以下红色行：
```
Failed to launch 'appie://login-exit?code=…' because the scheme does not have a registered handler.
```
复制从 appie:// 到结束引号之间的内容，并粘贴到聊天中。该代码只能使用一次且很快就会过期，因此请立即粘贴。

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

登录信息的存储位置

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

OS	位置
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 设为其他端口。

在服务器上运行

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 服务运行在反向代理之后，并通过 npm 安装：

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

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

在 /home/albert-heijn-mcp/.env 中配置：
```
AH_MCP_BASE_URL=https://albert-heijn-mcp.example.com
AH_MCP_TOKEN=<output of: openssl rand -hex 32>
```
设置为仅服务可读：sudo chown albert-heijn-mcp: /home/albert-heijn-mcp/.env && sudo chmod 600 /home/albert-heijn-mcp/.env。

使用软件包附带的服务单元安装（该单元以 --remote 模式运行）：

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

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

**使用反向代理添加 TLS，**并将请求转发到 127.0.0.1:3000。使用 Caddy 时：
```
albert-heijn-mcp.example.com {
    reverse_proxy 127.0.0.1:3000
}
```

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

AH_TOKENS_PATH=./server-tokens.json npx -y albert-heijn-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-mcp -g albert-heijn-mcp -m 700 /home/albert-heijn-mcp/.config/albert-heijn-mcp && install -o albert-heijn-mcp -g albert-heijn-mcp -m 600 $HOME/ah-tokens.json /home/albert-heijn-mcp/.config/albert-heijn-mcp/tokens.json.new && mv /home/albert-heijn-mcp/.config/albert-heijn-mcp/tokens.json.new /home/albert-heijn-mcp/.config/albert-heijn-mcp/tokens.json && rm $HOME/ah-tokens.json"'

服务器会在下次请求时读取该信息；无需重启。单独的文件可将你计算机上的登录信息与服务器隔开：AH 每次续期都会替换登录信息，因此每个登录信息只能在一个地方使用。在没有 SSH 的主机上，将其上传到服务器存储登录信息的位置：AH_TOKENS_PATH，或运行服务的用户的默认位置。

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

配置

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

变量	默认值	描述
`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 个字符；未设置时不会启动传输。你需要在 OAuth 登录页面输入此密钥；它也用于签署 OAuth 令牌。
`AH_LOG_FILE`	—	同时将日志追加到此文件。日志始终输出到 stderr。

命令行标志：

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

stdio（默认值）用于本地客户端；streamable-http 在 /mcp 提供 MCP 服务，并在 /authorize 提供 OAuth 登录。login 会从终端登录 Albert Heijn、保存令牌并退出；使用 --remote 时，它会要求输入代码，而不是打开登录窗口。

工具

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

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

账户

工具	描述
`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`	最近的店内收据（小票）。
`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/olekpuchka/albert-heijn-mcp
cd albert-heijn-mcp
npm ci
npm run build    # compile to dist/
npm run lint     # type-check

在检出目录中运行 node dist/index.js，或者在客户端的配置中将 /path/to/albert-heijn-mcp/dist/index.js 设为参数，并将 node 设为命令。

路径	内容
`src/index.ts`、`src/config.ts`、`src/loginCommand.ts`	入口点、标志和设置，以及 `login` 命令
`src/ahapi/`	使用 Node 内置 `fetch` 调用 AH REST 和 GraphQL API 的客户端
`src/auth/`	登录窗口、登录代码交换、令牌存储和刷新
`src/server/`	可流式传输的 HTTP 传输和 OAuth 登录
`src/tools/`	MCP 工具，每个领域对应一个文件
`deploy/`	随软件包提供的 systemd 单元
`manifest.json`、`.mcpbignore`	`.mcpb` 软件包的清单，以及其中排除的文件
`listing/`	连接器设置和应用目录中使用的名称、描述和图标（说明）
`.github/`	CI、发布工作流、Dependabot 和固定版本的 `mcp-publisher` 安装
`assets/`	本 README 的徽标和 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 中的两个位置以及 manifest.json 中更新版本，然后将更改合并到 main，并推送标签：git tag v1.2.3 && git push origin v1.2.3。只有仓库管理员可以创建 v* 标签。发布工作流会检查版本是否一致、构建软件包、将其作为 albert-heijn-mcp.tgz 连同 albert-heijn-mcp.mcpb 软件包一起附加到 GitHub 发布，并通过可信发布将软件包提交到 npm 暂存，因此无需存储 npm 令牌。在 npmjs.com 上（或使用 npm stage approve）批准暂存版本，使其正式发布；随后，工作流会更新 MCP Registry 条目。发布时不会附带说明；请在 GitHub 上撰写。