APC Overnight MCP

apc-mcp

通过任何兼容 MCP 的 AI（如 Claude、Cursor 或 Windsurf）预订、打印标签、追踪和取消 APC Overnight 包裹。

基于 APC Overnight New Horizon API v3 构建（集成指南版本 2.0.5）。

功能

向任何支持 MCP 的 AI 提供六种工具：

工具	功能
book_shipment	创建货运单，返回 22 位运单号。
book_batch_and_label	一次预订多件货物，并获取包含所有标签、可直接打印的合并 PDF。
get_label	将运输标签保存到磁盘，支持 PDF、ZPL（热敏打印机）或 PNG。
track_shipment	获取当前状态和完整追踪记录。
cancel_shipment	在货物正式交运前取消货运单。
list_services	列出此 MCP 支持的所有 APC 服务及其 ProductCodes。

底层使用你的 APC 账户凭据，通过 https://apc.hypaship.com/api/3.0 进行通信。

提示词示例

在 AI 客户端中安装 MCP 后，你可以这样提出要求：

“预订次日取件，从我们的仓库运到 Alex Taylor，地址为 45 High Street, Manchester M1 1AA，15 kg，1 件包裹，参考号 INV-4412。”

“预订周六 12:00 送到这个地址，然后给我 PDF 格式的标签。”

“追踪本周所有 APC 货运单。哪些还没有送达？”

“把这五个运单号的标签打印成 ZPL，这样我就能发送到热敏打印机。”

“这里有十笔订单——全部预订 APC 次日达，并给我一份可以打印的 PDF。”（AI 调用 book_batch_and_label 并返回合并 PDF 的路径。）

“取消运单 2018041910099660000599。客户取消了订单。”

“明天中午前送达的最便宜 APC 服务是什么？”（AI 调用 list_services 并进行判断）

AI 会处理地址解析、服务选择和错误恢复。业务决策由你来做。

企业工作流创意

将此 MCP 接入任何 AI Agent，即可自动处理实际发货业务：

• 每日订单履行。 每天早晨，AI 从你的电商平台读取新订单，为每笔订单选择合适的服务级别并通过 APC 预订，然后将追踪号发送给客户。
• 热敏打印机工作流。 获取 ZPL 格式的标签，直接发送到 Zebra、Rollo 或类似打印机，无需转换 PDF。
• 当日截单时间分流。 APC 截单前，AI 检查哪些订单仍符合上午 10 点前次日达服务的条件，哪些适合标准次日达，并为每笔订单预订可用的最快服务。
• 批量货运清单。 把包含数百票货物的电子表格交给 AI。AI 会全部完成预订，按分拨站将标签归组到单独文档中，并标记验证失败的货物。
• 多承运商比选。 与 royalmail-mcp 一起安装后，AI 可在预订时比较 APC 和 Royal Mail，并为每个目的地选择最便宜或最快的选项。
• 客户服务分流。 客户询问包裹去向时，AI 会调用 track_shipment，用通俗易懂的语言总结最新扫描记录，并起草回复。

兼容性

适用于任何支持 stdio 传输的 MCP 客户端：

• Claude Desktop
• Cursor
• Windsurf
• Claude Code
• Zed

ChatGPT、Smithery 等仅支持远程连接的 MCP 客户端需要 HTTP 传输，而当前版本尚未提供。如果你需要此功能，请提交 issue，方便我优先处理。

安装

npm install -g apc-mcp

或者无需安装即可运行：

npx apc-mcp

配置

您的 APC 凭据与登录 APC 门户时使用的凭据相同：

[email protected]
APC_PASSWORD=your-apc-account-password
APC_BASE_URL=https://apc.hypaship.com/api/3.0

可将其放在服务旁边的 .env 文件中，也可通过 MCP 客户端的配置设置（见下文）。

测试时请使用 https://apc-training.hypaship.com/api/3.0。APC 提供了一个培训端点，不会向您的账户收费，也不会寄送真实包裹。

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "apc": {
      "command": "npx",
      "args": ["-y", "apc-mcp"],
      "env": {
        "APC_USERNAME": "[email protected]",
        "APC_PASSWORD": "your-password"
      }
    }
  }
}

Cursor

添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "apc": {
      "command": "npx",
      "args": ["-y", "apc-mcp"],
      "env": {
        "APC_USERNAME": "[email protected]",
        "APC_PASSWORD": "your-password"
      }
    }
  }
}

支持的服务

以下是一些最常见的代码 — 运行 list_services 可查看完整目录，其中包含 60 多个 ProductCode，涵盖 APC 的所有产品类型。

Key	APC 服务	ProductCode
next-day	次日包裹，16:00 前送达（标准）	ND16
next-day-1200	次日包裹，12:00 前送达	ND12
next-day-1000	次日包裹，10:00 前送达	ND10
next-day-0900	次日包裹，09:00 前送达	ND09
two-five-day	2–5 日包裹（经济型）	TDAY
saturday-1200	周六包裹，12:00 前送达	NS12
next-day-light	次日轻型包裹，16:00 前送达	LW16
courier-pack	次日快递包裹，16:00 前送达	CP16
mail-pack	次日邮寄包裹，16:00 前送达	MP16
liquid	次日液体产品，16:00 前送达	LP16
limited-quantity	次日限量产品，16:00 前送达	LQ16
non-conveyable	次日不可传送包裹，16:00 前送达	NC16
excess	次日超尺寸包裹，16:00 前送达	XS16
ireland-road	爱尔兰 2–5 日陆运服务	ROAD
second-class-mail	二级邮件（Whistl）	POST

此外还有 45 种，包括每种产品类型的所有 09:00 / 10:00 / 12:00 时效选项、每种周六配送选项，以及轻型包裹、快递包裹、邮寄包裹、液体和不可传送包裹的 2–5 日经济型服务。

您可以传入易读键（next-day）或原始 ProductCode（ND16）。两种方式都可用。您的账户可使用哪些服务取决于 APC 合同 — 遇到不常见的代码时，请向您的配送站确认。

说明

• get_label 会在 APC 生成标签期间自动重试，最长约 15 秒，因此通常无需在 book_shipment 和 get_label 之间暂停。
• cancel_shipment 仅在包裹生成清单前有效。包裹一旦由 APC 揽收，您就必须通过 APC 门户取消。
• 标签格式：标准打印机使用 PDF，Zebra 或 Rollo 热敏打印机使用 ZPL，屏幕显示使用 PNG。

账户特定的服务可用性

并非每个 APC 账户都启用了所有 ProductCode。限时服务（09:00、10:00）、2–5 日经济型服务（TDAY）和专用产品（液体、限量产品、不可传送包裹）通常是附加服务，需要联系配送站启用。

如果看到以下响应，说明是账户或路由问题 — 不是此 MCP 中的 bug：

• 228 NO Services available — 您的账户未针对这组取件/配送邮政编码启用所请求的服务。
• 119 ProductCode (XXXX) is not one of the possible options — 您的合同中完全不包含该代码。

请联系 APC 配送站或 CMS Team（01922 702587）启用其他服务。

多件托运

当 numberOfPieces > 1 时，MCP 会自动将 totalWeightKg 平均分配到各个包裹，并为每件包裹发送一条 Item 条目（APC 要求 NumberOfPieces 与条目数量一致）。如果每件包裹需要不同的重量或尺寸，请传入完整的 items 数组 — MCP 会原样使用。

安全

你的 APC 用户名和密码可提供对你账户的完整访问权限。请像对待密码一样妥善保管。

• 切勿将 .env 提交到 git。本仓库中的 .gitignore 已将其排除。
• 不要在聊天消息或共享文档中粘贴凭据。
• 如果凭据泄露，请在 APC 门户中更换。

隐私与数据处理

此 MCP 完全在你的计算机上运行。没有任何客户数据、凭据或 API 流量会经过作者拥有或运营的服务器。

数据流向如下：

• 你提供给 AI 助手的配送详情会发送给你的 AI 提供商（例如，使用 Claude 时会发送给 Anthropic），并由你的账户承担。
• 预订请求会使用你的 APC 凭据发送至 APC Overnight。
• 标签会保存在你的本地磁盘 ~/Downloads/parcel-toolkit/ 中（可通过 PARCEL_TOOLKIT_LABELS_DIR env var 覆盖）。

如果你在英国企业中使用此工具，根据 UK GDPR，你是数据控制者。实用建议：

1. 使用 Claude Team、Claude Enterprise 或直接使用 Claude API，不要使用面向消费者的 Claude.ai，以便与 Anthropic 签订数据处理协议。对于面向消费者的套餐，至少应在隐私设置中关闭“帮助改进 Claude”。
2. 在隐私政策中将 Anthropic 和 APC Overnight 列为子处理方，做法与列出支付服务提供商或电子邮件服务相同。
3. 未经额外法律审查，请避免将此工具用于特殊类别数据（健康、生物识别、儿童数据）。
4. 本软件按原样提供，采用 MIT 许可。作者不是数据处理方，也不对你的合规义务承担责任——这些义务由你作为数据控制者承担。

贡献

欢迎在 github.com/catrinmdonnelly/apc-mcp 提交问题和拉取请求。如果 APC 更改了其 API，或你遇到与你的账户类型有关的边缘情况，请提交问题，并附上你发送的请求正文和收到的响应（请先删除凭据）。

配套 MCP

关于 Royal Mail Click & Drop，请参阅 royalmail-mcp。

免责声明

本项目与 APC Overnight Ltd. 无关联，未获其认可或赞助。“APC Overnight”和“New Horizon”是其各自所有者的商标。使用风险由你自行承担。

许可

MIT。请参阅 LICENSE。