royalmail-mcp

通过任何兼容 MCP 的 AI（如 Claude、Cursor 或 Windsurf）预订、标记、追踪和取消皇家邮政 (Royal Mail) 和 Parcelforce 货件。

已针对实时 Click & Drop API（2026 年 4 月）进行验证。预订、追踪和取消功能已通过端到端测试。标签获取功能已根据 OBA 账户规范进行验证。

功能介绍

为任何支持 MCP 的 AI 提供六个工具：

底层通过您的 Click & Drop API 密钥与 https://api.parcel.royalmail.com/api/v1 进行通信。

Related MCP server: UK Property Intelligence

提示词示例

一旦在您的 AI 客户端中安装了 MCP，您可以这样说：

“预订一份寄往 Alex Taylor 的一等信件，地址是 45 High Street, Manchester M1 1AA，重量 80 克。参考编号为 ORDER-1842。”

“通过 Tracked 48 发送这三个订单，并给我订单标识符。”（粘贴地址列表）

“预订一份下午 1 点前送达的 Special Delivery，保价 1000 英镑，寄往此地址，然后获取标签。”

“取消订单 1004。客户填错了邮编。”

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

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

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

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

企业工作流建议

接入任何 AI 代理后，此 MCP 可以自动化实际的货运操作：

• 日常订单履行。 每天早上，您的 AI 从 Shopify、WooCommerce 或电子表格中读取新订单，通过皇家邮政以正确的服务级别预订每个订单，并将追踪号码回传给客户。

• 客户服务分流。 当客户询问“我的包裹在哪里？”时，您的 AI 调用 track_order，用通俗易懂的语言总结最新状态，并起草回复。

• 退货处理。 客户申请退货。您的 AI 读取请求，预订正确的退货服务，并直接通过电子邮件发送可打印的标签，无需人工干预。

• 多承运商拣选。 与 apc-mcp 一起安装，您的 AI 可以在预订时比较皇家邮政和 APC，并为每个目的地选择最便宜或最快的选项。

• 批量履行日。 对于促销活动或订阅盒发货，给您的 AI 提供一个包含数百个订单的 CSV 文件。它可以在一次运行中以正确的服务和保价等级预订所有订单，然后为您提供摘要。

• 结账报价。 当客户在结账时询问运费时，您的 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"
      }
    }
  }
}

支持的服务

另有 22 种服务，包括签收变体、年龄验证服务和 Parcelforce 国际服务。运行 list_services 获取完整列表。

您可以传递友好键值（如 first-class）或原始服务注册代码（如 OLP1）。两者均可使用。您的账户可以使用哪些服务取决于 Click & Drop → Settings → Shipping services 中启用的内容。

限制

标签需要 OBA 账户

get_label 仅适用于拥有皇家邮政 在线商业账户 (OBA)（即开票商业账户）的客户。标准即付即用 (Pay-as-you-go) 的 Click & Drop 账户在调用 get_label 时会收到 403 Forbidden (Feature not available) 错误。

预订、追踪和取消功能适用于所有账户类型。如果您没有 OBA，仍然可以通过此 MCP 自动化订单创建，然后手动在 Click & Drop UI 中打印标签。

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

OBA 用户：启用自动应用邮资

如果您使用 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 密钥发送给皇家邮政 Click & Drop。

• 标签保存到您的本地磁盘 ~/Downloads/parcel-toolkit/（可通过 PARCEL_TOOLKIT_LABELS_DIR 环境变量覆盖）。

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

1. 使用 Claude Team、Claude Enterprise 或直接使用 Claude API（而非消费者版 Claude.ai），以确保与 Anthropic 签署了数据处理协议 (DPA)。在消费者版本中，请至少在隐私设置中关闭“帮助改进 Claude”。

2. 在您的隐私政策中将 Anthropic 和皇家邮政列为子处理者，就像您列出支付提供商或电子邮件服务一样。

3. 除非经过额外的法律审查，否则请避免将此工具用于特殊类别数据（健康、生物识别、儿童数据）。

4. 本软件按“原样”提供，受 MIT 许可协议约束。作者不是数据处理者，不对您的合规义务承担任何责任——这些义务由您作为数据控制者承担。

贡献

欢迎在 github.com/catrinmdonnelly/royalmail-mcp 提交 issue 和 pull request。如果皇家邮政更改了其 API，或者您的账户类型遇到了边缘情况，请提交包含您发送的请求体和收到的响应的 issue（请先清除您的 API 密钥）。

配套 MCP

对于 APC Overnight，请参阅 apc-mcp。

免责声明

本项目不隶属于皇家邮政集团有限公司，也不受其认可或赞助。“Royal Mail”、“Parcelforce”和“Click & Drop”是其各自所有者的商标。使用风险自负。

许可

MIT。请参阅 LICENSE。