Royalmail Mcp

royalmail-mcp

通过任何兼容 MCP 的 AI（例如 Claude、Cursor 或 Windsurf）预订 Royal Mail 和 Parcelforce 的货件、生成标签、跟踪货件并取消货件。

已针对线上 Click & Drop API 验证（2026 年 4 月）。已通过端到端测试验证预订、跟踪和取消功能。针对 OBA 账户的规范验证了标签获取功能。

功能介绍

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

工具	功能
book_order	在 Click & Drop 中创建订单。返回 orderIdentifier。
book_batch_and_label	一次预订多个订单，并获取包含所有标签的单个合并 PDF，可直接打印。
get_label	将邮资标签保存为 PDF 到磁盘。需要 OBA 账户（见下文）。
track_order	查询当前状态、跟踪号码和发货日期。
cancel_order	在订单生成货运清单前取消订单。不收取费用。
list_services	列出此 MCP 支持的所有 Royal Mail 和 Parcelforce 服务及其代码。

底层通过你的 Click & Drop API 密钥调用 https://api.parcel.royalmail.com/api/v1。

提示词示例

在 AI 客户端中安装 MCP 后，你可以这样说：

“预订一封 1st class 信件，寄给 Alex Taylor，地址是 45 High Street, Manchester M1 1AA，重 80 克。订单参考号设为 ORDER-1842。”

“用 Tracked 48 寄出这三个订单，并告诉我它们的 orderIdentifier。”（粘贴地址列表）

“为这个地址预订 Special Delivery by 1pm，赔偿金额为 £1,000，然后获取标签。”

“取消订单 1004。客户提供了错误的邮政编码。”

“500g 包裹最便宜的签收服务是什么？”（AI 调用 list_services 并进行判断）

“跟踪订单 1002、1003 和 1004，并总结每个订单的状态。”

“这里有十个订单——全部通过 Royal Mail Tracked 24 预订，并给我一份可打印的 PDF。”（AI 调用 book_batch_and_label 并返回合并 PDF 的路径。）

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

企业工作流思路

将此 MCP 接入任何 AI Agent，即可自动化实际的发货操作：

• 每日订单履行。 每天早上，AI 从 Shopify、WooCommerce 或电子表格中读取新订单，通过 Royal Mail 按合适的服务等级逐一预订，并将跟踪号码发送给客户。
• 客户服务分流。 客户发来“我的包裹到哪了？”的邮件时，AI 调用 track_order，用通俗语言总结最新状态，并起草回复。
• 退货处理。 客户申请退货后，AI 读取申请内容，预订合适的退货服务，并直接通过邮件将可打印的标签发回，全程无需员工介入。
• 多承运商选择。 与 apc-mcp 一同安装后，AI 可在预订时比较 Royal Mail 和 APC，并为每个目的地选择最便宜或最快的选项。
• 批量发货日。 促销活动或订阅盒发货时，将包含数百个订单的 CSV 提供给 AI。它会在一次操作中按合适的服务和赔偿等级预订所有订单，然后为你提供汇总。
• 结账运费报价。 客户在结账时询问运费，AI 会根据重量和邮政编码选择合适的服务、计算价格，并在几秒内回复。

兼容性

适用于所有支持 stdio 传输的 MCP 客户端：

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

ChatGPT、Smithery 和其他仅支持远程连接的 MCP 客户端需要 HTTP 传输，目前尚未提供。如果这对你很重要，请提交 issue，以便我优先处理。

安装

npm install -g royalmail-mcp

或者无需安装即可运行：

npx royalmail-mcp

配置

从 Click & Drop → Settings → API credentials 获取 API 密钥，然后设置：

RM_API_KEY=your-royal-mail-api-key
RM_BASE_URL=https://api.parcel.royalmail.com/api/v1

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

Claude Desktop

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

{
  "mcpServers": {
    "royalmail": {
      "command": "npx",
      "args": ["-y", "royalmail-mcp"],
      "env": {
        "RM_API_KEY": "your-royal-mail-api-key"
      }
    }
  }
}

Cursor

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

{
  "mcpServers": {
    "royalmail": {
      "command": "npx",
      "args": ["-y", "royalmail-mcp"],
      "env": {
        "RM_API_KEY": "your-royal-mail-api-key"
      }
    }
  }
}

支持的服务

键	Royal Mail 服务	代码
first-class	1st Class	OLP1
first-class-signed	Signed For 1st Class	OLP1SF
second-class	2nd Class	OLP2
tracked-24	Tracked 24	TOLP24
tracked-48	Tracked 48	TOLP48
special-delivery-750	Special Delivery by 1pm (£750)	SD1OLP
special-delivery-1000	Special Delivery by 1pm (£1,000)	SD2OLP
special-delivery-2500	Special Delivery by 1pm (£2,500)	SD3OLP
parcelforce-24	Parcelforce express24	PFE24
parcelforce-48	Parcelforce express48	PFE48
international-tracked	International Tracked	ITROLP

此外还有 22 种服务，包括签收服务、年龄验证服务和 Parcelforce 国际服务。运行 list_services 查看完整列表。

你可以传入易读的键（first-class）或原始 Service Register 代码（OLP1）。两者均可使用。你的账户可使用哪些服务，取决于 Click & Drop → Settings → Shipping services 中启用的服务。

限制

标签需要 OBA 账户

get_label 仅适用于 Royal Mail Online Business Account (OBA)（即月结商业账户）的客户。标准的按需付费 Click & Drop 账户调用 get_label 时会收到 403 Forbidden (Feature not available)。

所有账户类型都可以预订、追踪和取消。如果你没有 OBA，仍可通过此 MCP 自动创建订单，然后在 Click & Drop 界面中手动打印标签。

可在 auth.parcel.royalmail.com/register/oba 注册 OBA。

OBA 用户：启用 auto-apply-postage

如果你使用 OBA，还需在 Click & Drop → Settings 中勾选 "Apply postage automatically on orders imported via API"。否则，订单会保持为草稿，get_label 会返回 "Label generation only available for orders with postage applied status"。

安全

你的 API 密钥可完全访问 Click & Drop 账户。请像对待密码一样妥善保管。

• 切勿将 .env 提交到 git。此仓库中的 .gitignore 已将其排除。
• 不要将密钥粘贴到聊天消息或共享文档中。
• 如果密钥泄露，请前往 Click & Drop → Settings → API credentials 轮换密钥。

隐私与数据处理

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

数据流向如下：

• 你提供给 AI 助手的寄件详情会发送给你的 AI 提供商（例如，如果你使用 Claude，则会发送给 Anthropic），并使用你的账户。
• 预订请求会使用你的 API 密钥发送至 Royal Mail Click & Drop。
• 标签会保存在你的本地磁盘上的 ~/Downloads/parcel-toolkit/（可通过 PARCEL_TOOLKIT_LABELS_DIR 环境变量覆盖）。

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

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

贡献

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

配套 MCP

如需 APC Overnight，请参阅 apc-mcp。

免责声明

此项目与 Royal Mail Group Ltd. 无关，未获其认可或赞助。“Royal Mail”、“Parcelforce”和“Click & Drop”是各自所有者的商标。使用风险由你自行承担。

许可证

MIT。请参阅 LICENSE。