royalmail-mcp

royalmail-mcp

Book, label, track and cancel Royal Mail and Parcelforce shipments from any MCP-compatible AI such as Claude, Cursor, or Windsurf.

Verified against the live Click & Drop API (April 2026). Booking, tracking and cancellation tested end-to-end. Label retrieval verified against the spec for OBA accounts.

What it does

Exposes five tools to any AI that speaks MCP:

Under the hood it talks to https://api.parcel.royalmail.com/api/v1 using your Click & Drop API key.

Example prompts

Once the MCP is installed in your AI client, you can say things like:

"Book a 1st class letter to Alex Taylor, 45 High Street, Manchester M1 1AA, 80 grams. Reference it ORDER-1842."

"Ship these three orders via Tracked 48 and give me the orderIdentifiers." (paste a list of addresses)

"Book Special Delivery by 1pm with £1,000 compensation to this address, then fetch the label."

"Cancel order 1004. The customer sent the wrong postcode."

"What's the cheapest signed-for service for a 500g parcel?" (AI calls list_services and reasons)

"Track orders 1002, 1003 and 1004 and summarise where each one is."

The AI handles address parsing, service selection and error recovery. You handle the business decisions.

Workflow ideas for businesses

Plugged into any AI agent, this MCP can automate real shipping operations:

• Daily order fulfilment. Every morning, your AI reads new orders from Shopify, WooCommerce or a spreadsheet, books each one via Royal Mail at the right service level, and posts tracking numbers back to the customer.
• Customer service triage. When a customer emails "where's my parcel?", your AI calls track_order, summarises the latest status in plain English, and drafts a reply.
• Returns handling. A customer requests a return. Your AI reads the request, books the correct return service, and emails the printable label straight back, with no staff time involved.
• Multi-carrier picking. Installed alongside apc-mcp, your AI compares Royal Mail and APC at booking time and picks the cheapest or fastest option per destination.
• Bulk fulfilment days. For sale events or subscription-box drops, give your AI a CSV of hundreds of orders. It books them all at the right service and compensation tier in one run, then hands you a summary.
• Checkout quotes. When a customer asks for shipping cost at checkout, your AI picks the right service for the weight and postcode, calculates the price, and responds within seconds.

Compatibility

Works with any MCP client that supports stdio transport:

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

ChatGPT, Smithery and other remote-only MCP clients need an HTTP transport, which isn't included yet. If that matters to you, open an issue so I can prioritise it.

Install

npm install -g royalmail-mcp

Or run without installing:

npx royalmail-mcp

Configuration

Get your API key from Click & Drop → Settings → API credentials, then set:

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

Either in a .env file next to the server, or via your MCP client's config (see below).

Claude Desktop

Add to ~/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

Add to ~/.cursor/mcp.json:

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

Supported services

Plus 22 more, including signed-for variants, age-verification services, and Parcelforce international. Run list_services for the full list.

You can pass either the friendly key (first-class) or the raw Service Register code (OLP1). Both work. Which services your account can use depends on what's enabled in Click & Drop → Settings → Shipping services.

Limitations

Labels require an OBA account

get_label only works for customers on a Royal Mail Online Business Account (OBA), the invoiced business account. Standard Pay-as-you-go Click & Drop accounts will get 403 Forbidden (Feature not available) on get_label.

Booking, tracking and cancelling work on all account types. If you don't have an OBA you can still automate the order creation via this MCP, then print labels in the Click & Drop UI manually.

Register for OBA at auth.parcel.royalmail.com/register/oba.

OBA users: enable auto-apply-postage

If you're on OBA, also tick "Apply postage automatically on orders imported via API" in Click & Drop → Settings. Without it, orders stay as drafts and get_label returns "Label generation only available for orders with postage applied status".

Security

Your API key grants full access to your Click & Drop account. Treat it like a password.

• Never commit .env to git. The .gitignore in this repo already excludes it.
• Don't paste your key into chat messages or shared documents.
• Rotate it at Click & Drop → Settings → API credentials if it's ever exposed.

Contributing

Issues and pull requests are welcome at github.com/catrinmdonnelly/royalmail-mcp. If Royal Mail changes their API, or you hit an edge case on your account type, please open an issue with the request body you sent and the response you got (scrub your API key first).

Companion MCP

For APC Overnight, see apc-mcp.

Disclaimer

This project is not affiliated with, endorsed by, or sponsored by Royal Mail Group Ltd. "Royal Mail", "Parcelforce" and "Click & Drop" are trademarks of their respective owners. Use at your own risk.

Licence

MIT. See LICENSE.