royalmail-mcp
This server exposes MCP tools for automating Royal Mail and Parcelforce shipment management via the Click & Drop API.
book_order: Create a shipment by specifying service, weight, recipient address, and optional details (dimensions, reference, safe place instructions, notifications). Returns anorderIdentifier.book_batch_and_label: Book multiple orders simultaneously and receive a single merged PDF containing all shipping labels, ready for printing.get_label: Retrieve and save a postage label as a PDF for an existing order. (Requires a Royal Mail Online Business Account/OBA.)track_order: Get the current status, tracking number, and despatch date for an order.cancel_order: Cancel an order before it is manifested, with no charge applied.list_services: List all supported Royal Mail and Parcelforce services with their Service Register codes to help select the right option for weight, destination, and compensation needs.
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 six tools to any AI that speaks MCP:
Tool | What it does |
| Create an order in Click & Drop. Returns an |
| Book many orders at once and get back a single merged PDF of every label, ready to print. |
| Save the postage label to disk as a PDF. Requires an OBA account (see below). |
| Current status, tracking number and despatch date. |
| Cancel an order before it's manifested. No charge is applied. |
| Every Royal Mail and Parcelforce service this MCP supports, with codes. |
Under the hood it talks to https://api.parcel.royalmail.com/api/v1 using your Click & Drop API key.
Related MCP server: UK Property Intelligence
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_servicesand reasons)
"Track orders 1002, 1003 and 1004 and summarise where each one is."
"Here are ten orders — book them all on Royal Mail Tracked 24 and give me one PDF I can print." (AI calls
book_batch_and_labeland returns the path to a merged PDF.)
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-mcpOr run without installing:
npx royalmail-mcpConfiguration
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/v1Either 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
Key | Royal Mail service | Code |
| 1st Class |
|
| Signed For 1st Class |
|
| 2nd Class |
|
| Tracked 24 |
|
| Tracked 48 |
|
| Special Delivery by 1pm (£750) |
|
| Special Delivery by 1pm (£1,000) |
|
| Special Delivery by 1pm (£2,500) |
|
| Parcelforce express24 |
|
| Parcelforce express48 |
|
| International Tracked |
|
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
.envto git. The.gitignorein 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.
Privacy & data handling
This MCP runs entirely on your machine. No customer data, credentials or API traffic flows through any server owned or operated by the author.
The data path is:
Shipping details you give your AI assistant go to your AI provider (e.g. Anthropic, if you're using Claude) under your account.
Booking requests go to Royal Mail Click & Drop using your API key.
Labels are saved to your local disk at
~/Downloads/parcel-toolkit/(overridable via thePARCEL_TOOLKIT_LABELS_DIRenv var).
If you're using this in a UK business, you are the data controller under UK GDPR. Practical recommendations:
Use Claude Team, Claude Enterprise, or the Claude API directly — not consumer Claude.ai — so a Data Processing Agreement with Anthropic is in place. On consumer tiers, turn off "Help improve Claude" in Privacy settings at minimum.
List Anthropic and Royal Mail as subprocessors in your privacy policy, the same way you would list a payment provider or email service.
Avoid using this tool for special-category data (health, biometric, children's data) without additional legal review.
This software is provided as-is under the MIT licence. The author is not a data processor and takes no responsibility for your compliance obligations — those sit with you as the data controller.
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.
Available Tools
5 toolsbook_orderA
Book a Royal Mail shipment via Click & Drop. Returns an orderIdentifier used to retrieve the label.
| Name | Required | Description | Default |
|---|---|---|---|
| service | Yes | Royal Mail / Parcelforce service. Defaults to first-class (OLP1) if omitted. Raw Service Register codes (e.g. OLP1, TOLP24, PFE48) are also accepted. | |
| packageFormat | No | Package format. Determines which services are available and pricing | small-parcel |
| weightGrams | Yes | Total weight in grams (e.g. 500 for 500g) | |
| recipient | Yes | Recipient / delivery address | |
| sender | No | Sender address. Omit to use the address saved in your Click & Drop account | |
| reference | No | Your internal order or job reference | |
| subtotal | No | Order subtotal in GBP (used for customs/insurance) | |
| shippingCost | No | Shipping cost charged to recipient in GBP | |
| total | No | Order total in GBP | |
| despatchDate | No | Planned despatch date YYYY-MM-DD. Omit if your account does not allow future-dated orders | |
| requireSignature | No | Request signature on delivery | |
| safePlace | No | Safe place instructions e.g. "leave in porch" | |
| notifyEmail | No | Email address for delivery notifications | |
| notifyPhone | No | Mobile number for SMS delivery notifications | |
| dimensions | No | Package dimensions in mm (optional) | |
| goodsDescription | No | Brief description of contents | |
| specialInstructions | No | Special handling instructions |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description indicates the tool returns an orderIdentifier, which is useful. However, since no annotations are provided, the description carries full burden for behavioral disclosure. It does not mention mutability, side effects, prerequisites (e.g., account setup), or error conditions. It is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with 15 words, front-loading the key action and outcome. Every word serves a purpose. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (17 parameters, nested objects, no output schema), the description is concise but omits details like what happens on failure, pricing implications, or whether label retrieval is synchronous. However, the schema is well-documented, and the return value is stated. The description is nearly complete for the tool's core function.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, meaning all parameters include descriptions. The tool description itself does not repeat parameter details, but the schema already provides sufficient meaning. However, the description highlights the return value (orderIdentifier), which adds context beyond the schema. Given high schema coverage, baseline is 3, but the explicit mention of the return value and the tool's core action adds value, justifying a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to book a Royal Mail shipment via Click & Drop. It specifies the action (book), resource (shipment), and the system (Click & Drop), and mentions the return value (orderIdentifier). This distinguishes it from siblings like cancel_order, get_label, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus alternatives like cancel_order or list_services. It implies usage for booking shipments, but no exclusions or alternatives are mentioned. The context of sibling tools is present, but the description lacks explicit usage instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
cancel_orderA
Cancel a Royal Mail Click & Drop order. Must be done before the order is manifested/despatched.
| Name | Required | Description | Default |
|---|---|---|---|
| orderIdentifier | Yes | The orderIdentifier to cancel |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry full behavioral disclosure. It indicates a destructive action ('Cancel') but does not clarify if the cancellation is reversible, what happens to associated labels, or whether special permissions are needed. The description adds minimal behavioral context beyond the name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with zero waste. The first sentence states the core action, and the second provides a critical constraint. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (single param, no output schema, no annotations), the description is mostly adequate but lacks any mention of return values, error conditions, or side effects. It does not specify what happens on success or failure, which would help the agent handle responses.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single required parameter 'orderIdentifier', and the schema description is self-explanatory ('The orderIdentifier to cancel'). The description adds no additional parameter meaning, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Cancel', the resource 'Royal Mail Click & Drop order', and the critical precondition 'Must be done before the order is manifested/despatched', making the purpose unambiguous and distinct from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states a timing constraint ('before order is manifested/despatched') and implies this tool is for cancellation only. However, it does not mention what to do if the order is already manifested or suggest alternative tools like track_order for status checking.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_labelA
Get the shipping label for a Royal Mail Click & Drop order. Returns base64-encoded PDF label.
| Name | Required | Description | Default |
|---|---|---|---|
| orderIdentifier | Yes | The orderIdentifier returned when booking the order |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden. It reveals that the output is base64-encoded PDF, which is helpful. However, it does not mention any side effects, authentication needs, or whether it is a read-only operation (likely read-only but not explicit).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loads the core purpose, and includes a key detail about the return format. No extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with one parameter and no output schema, the description covers the essential purpose and output format. It could mention that the label is for printing or include a link to orderIdentifier documentation, but overall it is complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes the single parameter with high coverage (100%), and the description mentions it ('orderIdentifier returned when booking the order'). This adds context by linking the parameter to a previous step, which is useful but not transformative given schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get'), the resource ('shipping label'), and the context ('Royal Mail Click & Drop order'). It also specifies the return format ('base64-encoded PDF label'), which adds precision. This distinguishes it from siblings like book_order or cancel_order.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for retrieving a label after booking, but does not explicitly state when to use it versus alternatives. It mentions the input parameter ('orderIdentifier') but does not provide guidance on prerequisites or conditions for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_servicesA
List supported Royal Mail and Parcelforce services with their Service Register codes. Availability depends on your Click & Drop account.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses that the list may vary by account, which is a key behavioral trait (dynamic response based on account), and implies a read-only operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first states purpose and output, second adds important caveat. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and no output schema, the description is sufficient to understand what the tool does and its constraints. Could optionally mention return format (e.g., list of objects) but not essential.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has no parameters (0 params) and schema description coverage is 100%, so no additional param info needed. Description adds value by stating the output will include Service Register codes and account dependency.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it lists supported Royal Mail and Parcelforce services with Service Register codes, differentiating it from sibling tools like book_order or cancel_order by focusing on service listing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Mentions availability depends on Click & Drop account, implying account setup prerequisite, but no explicit when-to-use or comparison with siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
track_orderA
Get the current status and tracking details for a Royal Mail Click & Drop order.
| Name | Required | Description | Default |
|---|---|---|---|
| orderIdentifier | Yes | The orderIdentifier returned when booking the order |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the tool is read-only (Get) and focuses on status/tracking, which is appropriate. However, it does not disclose any behavioral traits like data freshness, rate limits, or potential errors. With no annotations, a 3 is reasonable but could be improved.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no waste. It front-loads the purpose and is appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one required parameter and no output schema, the description is largely complete. It explains the tool's purpose and expected input. Minor gap: it could mention that the output contains tracking details, but this is implied.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single parameter 'orderIdentifier' already described in schema. The description adds no additional meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get'), clearly identifies the resource ('current status and tracking details'), and specifies the domain ('Royal Mail Click & Drop order'). It distinguishes the tool from siblings like book_order or cancel_order.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (after booking an order, to check status/tracking), but does not explicitly state when not to use it or mention alternatives. Since there is no sibling with similar purpose, no explicit exclusion is needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
5 tool updates
v0.1.0- First observed
book_order - First observed
cancel_order - First observed
get_label - First observed
list_services - First observed
track_order
TDQS
Scored across 5 tools
Each tool targets a distinct operation (booking, canceling, label retrieval, service listing, tracking) with no overlapping purposes. The descriptions clearly differentiate their roles.
Tools follow a consistent verb_noun pattern (book_order, cancel_order, get_label, list_services, track_order). 'get_label' uses 'get' while others use verbs like 'book' and 'cancel', but the pattern is clear and predictable.
With 5 tools covering the essential operations for Royal Mail shipments (create, cancel, label, tracking, service discovery), the count is well-scoped and appropriate for the server's purpose.
The set covers the core lifecycle of an order (create, cancel, label retrieval, tracking). Missing features like updating an order or manifesting are minor gaps that can be worked around, as most workflows are supported.
Maintenance
Related MCP Connectors
Furgonetka MCP Server is an extension for LLMs (such as Claude) that integrates AI assistants with Poland's most popular courier brokerage platform. The server enables models to interact directly with services from various couriers (including InPost, DPD, DHL, UPS, and Poczta Polska) through a single, unified interface. With this integration, your AI stops just "writing about logistics" and starts actually managing it.
MCP server for EasyPost — rate shipments, buy & refund labels, track packages, verify addresses.
Multi-carrier shipping for AI agents: compare rates, buy labels, track packages, validate addresses
Shipmail MCP server for AI agent custom-domain email inboxes with REST API and webhooks.
Related MCP Servers
- AlicenseAqualityCmaintenanceMCP server for APC Overnight. Book, label, track and cancel UK parcel shipments from any MCP-compatible AI.66 npm2MIT
- AlicenseNot gradedqualityBmaintenanceUK property data MCP server for AI hosts (Claude, ChatGPT). Wraps Land Registry, Rightmove, EPC, rental yields, stamp duty, and Companies House into 13 tools.2MIT
- AlicenseBqualityDmaintenanceAn MCP server that wraps the ShipSaving logistics REST API, enabling AI assistants like Claude to perform shipping operations through natural language.3013 npmMIT
- AlicenseAqualityCmaintenanceMCP server for tracking Japanese logistics carriers (Yamato, Sagawa, Japan Post) via mock or AfterShip adapter. Enables AI agents to query shipment status and history in natural language.3MIT