mcpField
C
costco

costco

本地服务
github.com/thehesiod金融数据727 周前更新
代码仓库

关于 costco

costco 是一个让 Claude 读取 Costco 仓库收据和在线订单的 MCP 服务，也支持商品查询和多个账户。它通过浏览器会话中的 OAuth2 刷新令牌访问 Costco 未公开的内部 GraphQL API。

主要功能

  1. 01按日期列出仓库收据
  2. 02读取收据明细及商品信息
  3. 03按日期列出在线订单
  4. 04查询商品并缓存结果
  5. 05支持多个账户与令牌管理

适用场景

  1. 01汇总指定日期范围的仓库收据
  2. 02查看收据中的商品、数量和价格
  3. 03检查 Costco.com 订单状态与总额
  4. 04在个人和家庭账户间分别查询

MCP 相关

该 MCP 服务向 Claude 等 MCP 客户端提供 Costco 仓库收据、在线订单、商品查询和认证状态等工具。它使用从浏览器会话提取的 OAuth2 刷新令牌调用 Costco 内部 API。

配置

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

mcp.json · 通用配置
{
  "mcpServers": {
    "thehesiod-costco": {
      "command": "uvx",
      "args": [
        "costco-mcp-server"
      ]
    }
  }
}
启动命令uvx costco-mcp-server

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

安装包
pypicostco-mcp-server0.1.2

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

Costco MCP 服务

MCP Registry PyPI

一个 MCP（Model Context Protocol） 服务，可让 Claude 访问 Costco 仓库收据和在线订单。它通过从浏览器会话中提取的 OAuth2 刷新令牌，直接与 Costco 的内部 GraphQL API 通信——无需抓取，也无需在运行时启动无头浏览器。支持多账户（例如 personal、spouse），并为每个账户单独存储令牌。

可在 MCP Registry 中找到，名称为 io.github.thehesiod/costco。

免责声明

本项目与 Costco Wholesale Corporation 无关，也未获得其认可或赞助。“Costco”及所有相关名称、徽标和商标均为其各自所有者的财产。

本服务会与 Costco 的未公开内部 API通信——这些端点尚未发布，不保证稳定，且可能随时更改或被屏蔽，恕不另行通知。使用这些 API 可能违反 Costco 的服务条款；您有责任查阅服务条款并自行判断您的使用是否合规。

**使用风险由您自行承担。**作者和贡献者对使用本软件所产生的任何后果均不承担责任，包括但不限于：账户暂停或终止、数据丢失或损坏、收据／订单信息错误、购买失败、财务差异、触发 API 速率限制、IP 被屏蔽，或任何其他直接或间接损害。不提供任何担保——完整的 MIT 无担保条款请参阅 LICENSE。

如果 Costco 发布官方 API，则应将本项目视为已弃用，并改用官方 API。

功能

仓库
  • list_warehouse_receipts — 查询指定日期范围内的店内收据（条形码、仓库、总额）
  • get_receipt_detail — 根据条形码获取完整的逐项收据详情（商品、数量、价格、优惠券、部门代码）
  • get_all_receipt_details — 批量获取指定日期范围内每张收据的完整详情
在线订单
  • list_online_orders — 查询指定日期范围内的 Costco.com 订单（订单号、状态、商品、总额）
商品
  • lookup_products — 将商品编号解析为完整商品名称和部门。使用本地 SQLite 缓存（~/.costco-mcp/products.db），重复查询无需付费。
身份验证
  • check_auth_status — 报告令牌有效期并列出已配置的账户
  • save_refresh_token — 注册或更新账户的刷新令牌

设置

在 Claude Code 中安装
claude mcp add --transport stdio costco -- \
    uvx --from "costco-mcp-server @ git+https://github.com/thehesiod/costco-mcp" costco-mcp-server

在 发布到 PyPI 后，上述安装方式可简化为：

claude mcp add --transport stdio costco -- uvx costco-mcp-server
身份验证

Costco 不提供公开的 OAuth 应用，因此需要从浏览器的 Azure AD B2C 会话存储中提取刷新令牌。刷新令牌的有效期约为 90 天；每次 API 调用时都会自动签发 bearer 令牌。

半自动流程（推荐）。 使用专用的 Chrome 配置文件和 chrome-devtools-mcp，让 Claude 为你提取并注册令牌。完成首次设置后，每次重新验证只需“启动浏览器，让 Claude 刷新”。

  1. 启动身份验证浏览器（跨平台控制台脚本）：

    uvx --from "costco-mcp-server @ git+https://github.com/thehesiod/costco-mcp" costco-auth-browser

    Chrome 会在端口 9223 上启动，并使用位于 ~/.costco-mcp/chrome-profile/ 的持久化配置文件。

  2. 注册一个指向该端口的 chrome-devtools-mcp 实例（仅需一次）：

    claude mcp add costco-browser -- npx -y chrome-devtools-mcp --browserUrl http://127.0.0.1:9223

  3. 在启动的浏览器窗口中登录 costco.com（仅首次需要——配置文件会持久保存）。

  4. 让 Claude 刷新：

    提取我的 Costco 刷新令牌，并将其保存到账户“personal”。

    Claude 会通过 chrome-devtools-mcp 从 localStorage 中读取 msal.*.refreshtoken 条目，并调用 save_refresh_token。

手动备用方案。 如果你不想配置第二个 MCP：登录 costco.com，打开 DevTools → Application → Local Storage → https://www.costco.com，找到包含 refreshtoken 的键，从其 JSON 值中复制 secret 字段，然后：

uvx --from "costco-mcp-server @ git+https://github.com/thehesiod/costco-mcp" \
    costco-mcp-server --save-token personal <REFRESH_TOKEN>

多账户

每个工具都接受可选的 account 参数（例如 "personal"、"spouse"）。省略该参数时会使用默认账户（第一个注册的账户，或最近设置的账户）。各账户的数据按名称隔离存储在 ~/.costco-mcp/accounts/<name>/ 下。

工作原理

该服务使用 httpx[http2] 直接调用 Costco 的内部 GraphQL 端点：

  • ecom-api.costco.com/ebusiness/order/v1/orders/graphql — 仓库收据和在线订单
  • ecom-api.costco.com/ebusiness/product/v1/products/graphql — 商品查询

身份验证使用 Azure AD B2C（signin.costco.com）。auth.py 中内置的公开客户端 ID（租户、策略、MSAL/WCS 客户端 ID）随 Costco 自己的浏览器包一起发布，并非机密信息。此服务不会处理任何凭据（用户名/密码）。

有关架构详情和开发说明，请参阅 CLAUDE.md。

平台说明

完全跨平台（macOS、Linux、Windows）。不使用 shell 脚本——所有入口点都是 Python 控制台脚本。

半自动身份验证流程要求在标准位置安装 Chrome 或 Chromium。costco-auth-browser 会搜索：

  • macOS：/Applications/Google Chrome.app/...
  • Windows：%ProgramFiles%、%ProgramFiles(x86)%、%LocalAppData% 下的 Google\Chrome\Application\chrome.exe
  • Linux / 回退方案：在 PATH 中查找 google-chrome、google-chrome-stable、chromium、chromium-browser

使用 COSTCO_AUTH_PORT 覆盖调试器端口。

安全说明

  • 刷新令牌以明文形式存储在 ~/.costco-mcp/ 中。请依赖操作系统级别的主目录权限保护。
  • 此服务不会处理任何凭据。身份验证完全在浏览器中的 Costco 登录流程内进行。
  • auth.py 中的 Azure AD B2C 客户端 ID 是随 Costco 浏览器包一起发布的公开 SPA 标识符，并非机密信息。

许可证

MIT — 请参阅 LICENSE。

mcp-name: io.github.thehesiod/costco

评论

支持 Markdown

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。