migros-mcp

migros-mcp

让 Claude（及其他 AI 应用）搜索 Migros 的商品、食谱、门店和促销活动。登录后，还可以管理购物篮并查询订单、收据和 Cumulus 积分。

非官方。 并非由 Migros 制作或提供支持。它使用与 Migros 网站相同的幕后地址，因此 Migros 一旦更改这些地址，它就可能无法使用。使用风险自负。

安装

这是一个分支。 herp75/migros-mcp 是 lewpgs/migros-mcp 的版本，经过安全强化，包含实时测试和更多工具（参见 CHANGELOG）。它以 Docker 镜像 ghcr.io/herp75/migros-mcp 的形式提供，并已在 MCP Registry 中列为 io.github.herp75/migros-mcp。npm 包 migros-mcp 和 Claude Desktop 安装程序 migros-mcp.mcpb 是上游版本，并非此版本。

它会在你自己的电脑上运行，因此适用于可以启动程序的桌面应用：Claude Desktop、Claude Code、Cursor 等。它不能在浏览器中的 claude.ai 或 Claude 手机应用中运行。你需要 Docker 或 Podman。

将登录信息保存在只有你能读取的文件中。 如果只想搜索，可以跳过此步骤。

install -m 600 /dev/null ~/.config/migros-mcp.env
"${EDITOR:-nano}" ~/.config/migros-mcp.env

[email protected]
MIGROS_PASSWORD=your-password

每行一项，不要加引号。密码中的 $、# 和引号都没问题（Docker 会按文件原样读取）。如果想使用 2FA，而不必输入验证码，请添加 MIGROS_TOTP_SECRET=...（参见你的 Migros 账户）。

保存的登录信息位于 Docker 卷 migros-mcp 中，因此重启后仍会保留。这很重要：Migros 会封锁登录过于频繁的电脑。

Claude Code

claude mcp add migros -- docker run -i --rm \
  --env-file ~/.config/migros-mcp.env -v migros-mcp:/config \
  ghcr.io/herp75/migros-mcp:0.6

如果只想搜索，请省略 --env-file …。使用 Podman 时，将 docker 替换为 podman。

Claude Desktop、Cursor 和其他应用

将以下内容添加到应用的 MCP 配置文件中，并在路径中填写你的主文件夹：

• Claude Desktop： Settings > Developer > Edit Config
• Cursor： ~/.cursor/mcp.json（所有项目）或 .cursor/mcp.json（单个项目）

{
  "mcpServers": {
    "migros": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--env-file", "/home/you/.config/migros-mcp.env",
        "-v", "migros-mcp:/config",
        "ghcr.io/herp75/migros-mcp:0.6"
      ]
    }
  }
}

其他应用（VS Code、Windsurf、Zed 等）也运行相同的命令，但配置格式略有不同。请查看应用的 MCP 使用说明。

验证镜像（可选）

每个镜像都由此仓库的发布工作流使用 cosign 进行无密钥签名：

cosign verify ghcr.io/herp75/migros-mcp:0.6 \
  --certificate-identity-regexp '^https://github.com/herp75/migros-mcp/\.github/workflows/(docker|release)\.yml@' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

检查是否正常运行

开始新的聊天并提问："Search Migros for oat milk."

你的 Migros 账户

可选。没有账户也能使用商品搜索、商品详情、库存、门店、促销和食谱功能。

有了账户，Claude 还可以查看和修改你的购物篮与购物清单、查询订单、店内收据和 Cumulus 积分，并将 Cumulus 优惠券添加到你的卡片中。它绝不会下单或付款。它会提供结账链接，你可以自行前往 migros.ch 完成操作。

需要填写的内容取决于你登录 migros.ch 的方式：

登录方式	填写内容
电子邮件和密码	电子邮件和密码。完成。请使用从未在其他地方使用过的密码：服务会将其保存在你电脑上的文件中。
电子邮件、密码和身份验证器应用中的 6 位代码	电子邮件和密码。Claude 需要登录时，会向你询问当前代码。只有 Migros 结束已保存的登录状态时才会发生这种情况，不会在每次聊天时都发生。
与上一种相同，但你不想被要求输入代码	电子邮件、密码和你的设置密钥（见下文）。

查找你的设置密钥（仅最后一种选项需要）

设置密钥（也称为 TOTP 密钥）不是 6 位代码。它是一串较长的字母和数字，大约 32 位，例如 JBSWY3DPEHPK3PXP...，你首次将 Migros 添加到身份验证器应用时会获得它。它永远不会改变。

• 保存在密码管理器中了？ 打开 Migros 条目，查找类似“查看一次性密码密钥”的选项。如果看到以 otpauth:// 开头的链接，设置密钥就是 secret= 后面的部分。
• 没有保存在任何地方？ Migros 只会在设置 2FA 时显示该密钥。在 Migros 账户设置中移除 2FA，然后重新设置。在二维码下方有一个写着 “或者在身份验证器应用中输入以下密钥” 的文本框。完成设置前复制该密钥，并将新条目添加到身份验证器应用中。

将 MIGROS_TOTP_SECRET=... 作为另一行添加到 ~/.config/migros-mcp.env 中（参见 安装）。

只有身份验证器应用中的代码才可使用。如果你的账户仅使用通行密钥或短信验证码，请先在 Migros 账户设置中添加身份验证器应用。

设置

所有设置都是环境变量。使用 Docker 时，将它们放入 ~/.config/migros-mcp.env（参见 安装）。这些设置都不是必需的。

变量	默认值	作用
MIGROS_EMAIL	无	你的 Migros 登录电子邮件。没有电子邮件和密码时，只能使用无需账户的工具。
MIGROS_PASSWORD	无	你的 Migros 密码。它只会发送到 login.migros.ch。
MIGROS_TOTP_SECRET	无	2FA 设置密钥，这样就不会有人向你索要代码。它和第二个密码一样：请妥善保管。若它与密码保存在同一个文件中，任何拿到该文件的人都会同时获得两个验证因素。
MIGROS_MCP_UPDATE_CHECK	开启；镜像中关闭	设置为 false、0、off 或 no 可关闭每天对 GitHub 上此分支较新版本的检查（仅从源代码运行时有效）。
MIGROS_API_WRAPPER_USERAGENT	内置	覆盖进行无需账户的搜索时发送的浏览器名称。很少需要设置。
XDG_CONFIG_HOME（Linux）、APPDATA（Windows）	常规位置；镜像中为 /config	已保存登录信息（migros-mcp/session.json）的存放位置。在 Mac 上始终为 ~/Library/Application Support/migros-mcp/。

仅用于开发：MIGROS_TEST_EMAIL、MIGROS_TEST_PASSWORD、MIGROS_TEST_TOTP_SECRET、MIGROS_LIVE_ENV_FILE 和 MIGROS_LIVE_SESSION_DIR（参见 开发）。

你可以询问的内容

无需账户：

• “搜索 Migros 的蛋白棒”
• “这个商品的营养信息是什么？”
• “查找苏黎世附近的 Migros 门店”
• “Migros 现在有哪些促销活动？”
• “给我找一个意式烩饭食谱”

使用账户后：

• “我的 Migros 购物篮里有什么？”
• “往我的购物篮里加 2 升牛奶”
• “把这个食谱所需的食材加到我的购物篮里”
• “显示我最近 5 笔 Migros 订单”
• “我上个月在 Migros 花了多少钱？”
• “我上个月在哪些 Migros 门店购物，各花了多少钱？”
• “我有哪些 Cumulus 优惠券？激活咖啡优惠券。”
• “为周末创建一份新的购物清单”
• “给我结账完成页面的链接”

更新

:0.6 会跟随最新的 0.6.x 版本（仅包含修复）。要获取该版本，请拉取镜像并重启应用：

docker pull ghcr.io/herp75/migros-mcp:0.6

新功能会随新的次要版本发布（:0.7）：更改配置中的标签。版本发布信息列在发布页面和 CHANGELOG 中。镜像本身不会检查更新（其中的 MIGROS_MCP_UPDATE_CHECK 处于关闭状态）。

隐私与安全

• 你的电子邮箱、密码和设置密钥只会发送到 Migros 自己的登录页面（login.migros.ch）。你提供给 Claude 的 6 位验证码仅用于这一次登录，绝不会存储或记录。
• 你的密码和设置密钥保存在 ~/.config/migros-mcp.env 中，只有你能读取，不会放在应用的配置文件里。
• 登录后，保存的登录信息（Cookie 和访问令牌）会保留在你的电脑上，位于 Docker 卷 migros-mcp 中的 session.json 文件里。执行 docker volume rm migros-mcp 会让你退出登录。在该卷中，只有服务的用户可以读取这些信息。（不使用 Docker 时，Linux 上的路径为 ~/.config/migros-mcp/，Mac 上为 ~/Library/Application Support/migros-mcp/，Windows 上为 %APPDATA%\migros-mcp\。）
• 错误消息中会隐藏你的电子邮箱、密码、设置密钥、Cookie 和访问令牌。
• 会更改购物篮的工具会标记出来，这样你的应用就能在运行这些工具前征求你的同意。请保持此审批开启。
• 请亲自向 Claude 提供 6 位验证码。不要让能够操作你账户的 AI 同时读取你的验证码（例如从密码管理器中读取）：这样，它读取到的文本就可能让它登录，而第二重验证也就失去了作用。
• 商品说明、食谱和订单数据来自 Migros 和其他人。migros-mcp 会指示 AI 将这些内容视为信息，而不是指令。
• 它绝不会下单或付款。get_checkout_link 会提供一个链接，你可以在 migros.ch 上完成结账。
• 发现安全问题？请参阅 SECURITY.md。

故障排查

• “请求过多”或其他登录错误。 Migros 会阻止频繁登录的电脑。发生这种情况时，migros-mcp 会自行暂停尝试一段时间（最初为 30 秒，如果问题持续则会延长），并在当前登录仍然有效时继续使用。错误消息会说明暂停到什么时候。请等到该时间后再试。反复重启应用或输入错误密码会让情况变得更糟。
• 之前能用的功能现在失效了。 Migros 可能更改了其网站。请更新到最新版本（参见更新）；如果仍然失效，请提交问题。

工具

这些是 Claude 在后台调用的工具。使用它不需要了解这些工具。

Kind 列说明工具对你的账户执行什么操作：读取、更改（不会丢失任何内容）或删除（移除或覆盖内容）。你的应用会据此决定何时先征求你的同意。请对所有非读取操作保持审批开启。

无需账户（全部为读取）

工具	功能
search_products	按名称或关键词搜索商品，包括仅在线销售的商品（例如“Partner”商品）。
get_product_details	获取营养成分、配料、过敏原、价格和评分。仅在线销售的商品还会显示在线价格和 Partner 标记。
get_stock	查询某家门店是否有某商品的库存。每天更新一次。Migros 没有数据时显示“未知”。
get_categories	获取 Migros 的所有商品类别。
search_stores	搜索地点附近的门店，并显示地址和营业时间。
get_promotions	获取当前促销和优惠。
search_recipes	按文本和／或配料搜索 Migusto（Migros 的食谱网站）。仅支持德语、法语和意大利语。
get_recipe_details	获取完整食谱：配料、步骤、照片和营养信息。
get_recipe_products	获取 Migusto 为某道食谱推荐的 Migros 商品及其名称和价格，可直接用于 add_to_basket。

使用你的账户

工具	类型	功能
authenticate	修改	使用当前的 6 位数代码登录。仅在没有保存设置密钥时使用。
get_profile	读取	获取你的姓名、电子邮件和语言。
get_addresses	读取	获取你保存的配送地址和账单地址。
get_shopping_lists	读取	获取你的购物清单名称；适用于有多个清单的用户。
create_shopping_list	修改	创建一个新的空清单。
rename_shopping_list	删除	为清单更改名称（旧名称会被替换）。
delete_shopping_list	删除	删除清单及其商品。仅在你确认后执行，且不会删除你唯一的清单。
get_basket	读取	查看购物篮中的商品（购物篮即购物清单）。
add_to_basket	删除	添加商品（默认数量为 1）。如果商品已在购物篮中，新数量会替换原数量，而不是累加。
update_basket_quantity	删除	设置所需商品数量（设为 0 即移除）。
remove_from_basket	删除	移除商品。
set_item_note	删除	为商品添加备注，例如“无乳糖”（会替换之前的备注）。
get_checkout_link	读取	获取前往 migros.ch 完成结账的链接。所有清单使用同一个链接；如果有多个清单，请在 migros.ch 确认显示的是正确清单。
get_orders	读取	分页获取你的在线订单，并可按状态筛选。
get_order_details	读取	获取某个订单的完整信息。
get_cumulus_status	读取	获取你的 Cumulus 卡信息：本期累计积分、卡号、持卡人和会员资格。
get_cumulus_coupons	读取	获取你当前的个人 Cumulus 优惠券，以及可激活的优惠券。
activate_cumulus_coupon	修改	将优惠券添加到你的 Cumulus 卡中，以便下次购物时使用。不会购买任何商品。
deactivate_cumulus_coupon	修改	从卡中移除优惠券。
get_cumulus_bons	读取	获取你的 Cumulus 代金券。你需要在结账时自行兑换。
get_in_store_receipts	读取	按日期范围获取你的店内收据（Kassenbons）：门店、日期、金额和积分。
get_receipt_details	读取	获取 migros.ch 收据页面的链接，你可以在该页面打开收据查看商品（所有收据使用同一个链接；此服务无法获取收据中的商品）。

工作原理

- **无需账户**时，它会使用 [migros-api-wrapper](https://www.npmjs.com/package/migros-api-wrapper) 和 Migros 网站调用的相同地址，并在启动时获取访客令牌。 - **使用账户**时，它会像浏览器一样在 `login.migros.ch` 登录（先输入邮箱，再输入密码，然后输入 2FA 验证码，如果账户启用了 2FA），并保存登录信息。访问令牌只在短时间内有效，因此系统会使用已保存的登录信息静默续期，无需再次登录。只有 Migros 使已保存的登录失效时，才会完整登录一次。 - 保存登录信息很重要，因为 Migros 的登录页面位于 Cloudflare 防护之后，Cloudflare 会阻止频繁登录的计算机。 - 如果没有设置密钥，在确认账户需要验证码后，它会等到 Claude 有验证码时才发送密码。这样就不会启动无法完成的登录。

开发

代码布局以及如何添加工具：docs/architecture.md。贡献方式：CONTRIBUTING.md。

git clone https://github.com/herp75/migros-mcp.git
cd migros-mcp
npm install
npm run build
npm test

提交拉取请求前，请运行与 CI 相同的检查：

npm run typecheck      # TypeScript, including the tests
npm run lint           # ESLint
npm run format:check   # Prettier (npm run format fixes it)
npm run test:coverage  # tests, failing below 80 % line coverage of src/

git config blame.ignoreRevsFile .git-blame-ignore-revs 可让 git blame 忽略那次大型格式调整提交。

使用 Migros 实时网站检查无需账户的工具。GitHub 也会在每周一运行此检查，因此 Migros 方面的变更会及早显现：

npm run live-check

使用专用的测试账户（绝不要使用你自己的账户）检查需要账户的工具。将该账户的登录信息放入 .env.live（已被 git 忽略，chmod 600），变量名为 MIGROS_TEST_EMAIL、MIGROS_TEST_PASSWORD，以及在使用 2FA 时的 MIGROS_TEST_TOTP_SECRET。--write 还会将商品添加到购物篮、更改其数量，然后再将其移除，以检查购物篮最终是否恢复原样。测试登录信息保存在 .live-session/ 中，因此重复运行时无需每次重新登录。

Migros 会对来自 GitHub 服务器的登录请求进行机器人检查，因此此检查改为每周在一台计算机上运行：scripts/migros-live-check.sh 会拉取已发布的镜像（edge，由 main 构建），检查其 cosign 签名，并在 rootless podman 下于该镜像内使用 --write 运行检查，因此测试的是人们实际安装的内容，仓库中的任何内容都不会在容器外运行。它需要 podman、skopeo 和 cosign；已保存的测试登录信息保存在 ~/.local/state/migros-live-check/ 中。要安排运行时间，请将 scripts/systemd/migros-live-check.service 和 .timer 复制到 ~/.config/systemd/user/，并运行 systemctl --user enable --now migros-live-check.timer；结果位于 journalctl --user -u migros-live-check 中。GitHub 上的 live 工作流仍可手动启动，以查看 GitHub 的服务器是否再次能够通过检查。

npm run live-account              # read-only
npm run live-account -- --write   # with the basket round trip

使用 MCP Inspector 试用：

npx -y @modelcontextprotocol/inspector node dist/index.js

许可证

MIT，详见 LICENSE。