royalmail-mcp

Reserva, etiqueta, rastrea y cancela envíos de Royal Mail y Parcelforce desde cualquier IA compatible con MCP, como Claude, Cursor o Windsurf.

Verificado con la API en vivo de Click & Drop (abril de 2026). La reserva, el seguimiento y la cancelación han sido probados de extremo a extremo. La recuperación de etiquetas ha sido verificada según las especificaciones para cuentas OBA.

Qué hace

Expone seis herramientas a cualquier IA que hable MCP:

Internamente, se comunica con https://api.parcel.royalmail.com/api/v1 usando tu clave de API de Click & Drop.

Related MCP server: UK Property Intelligence

Ejemplos de prompts

Una vez que el MCP esté instalado en tu cliente de IA, puedes decir cosas como:

"Reserva una carta de 1ª clase para Alex Taylor, 45 High Street, Manchester M1 1AA, 80 gramos. Asígnala como ORDER-1842."

"Envía estos tres pedidos mediante Tracked 48 y dame los orderIdentifiers." (pega una lista de direcciones)

"Reserva Special Delivery antes de la 1pm con £1,000 de compensación para esta dirección, luego obtén la etiqueta."

"Cancela el pedido 1004. El cliente envió el código postal incorrecto."

"¿Cuál es el servicio certificado más barato para un paquete de 500g?" (la IA llama a list_services y razona)

"Rastrea los pedidos 1002, 1003 y 1004 y resume dónde está cada uno."

"Aquí hay diez pedidos: resérvalos todos en Royal Mail Tracked 24 y dame un PDF que pueda imprimir." (la IA llama a book_batch_and_label y devuelve la ruta a un PDF combinado.)

La IA se encarga del análisis de direcciones, la selección de servicios y la recuperación de errores. Tú te encargas de las decisiones comerciales.

Ideas de flujo de trabajo para empresas

Conectado a cualquier agente de IA, este MCP puede automatizar operaciones de envío reales:

• Cumplimiento de pedidos diario. Cada mañana, tu IA lee nuevos pedidos de Shopify, WooCommerce o una hoja de cálculo, reserva cada uno a través de Royal Mail con el nivel de servicio adecuado y publica los números de seguimiento de vuelta al cliente.

• Triaje de atención al cliente. Cuando un cliente envía un correo electrónico preguntando "¿dónde está mi paquete?", tu IA llama a track_order, resume el estado más reciente en lenguaje sencillo y redacta una respuesta.

• Gestión de devoluciones. Un cliente solicita una devolución. Tu IA lee la solicitud, reserva el servicio de devolución correcto y envía la etiqueta imprimible directamente por correo electrónico, sin intervención del personal.

• Selección de múltiples transportistas. Instalado junto a apc-mcp, tu IA compara Royal Mail y APC en el momento de la reserva y elige la opción más barata o rápida por destino.

• Días de cumplimiento masivo. Para eventos de ventas o envíos de cajas de suscripción, dale a tu IA un CSV de cientos de pedidos. Los reserva todos en el servicio y nivel de compensación correctos en una sola ejecución, luego te entrega un resumen.

• Cotizaciones en el checkout. Cuando un cliente pregunta por el costo de envío en el checkout, tu IA elige el servicio correcto para el peso y el código postal, calcula el precio y responde en segundos.

Compatibilidad

Funciona con cualquier cliente MCP que soporte transporte stdio:

• Claude Desktop

• Cursor

• Windsurf

• Claude Code

• Zed

ChatGPT, Smithery y otros clientes MCP remotos necesitan un transporte HTTP, que aún no está incluido. Si eso es importante para ti, abre un issue para que pueda priorizarlo.

Instalación

npm install -g royalmail-mcp

O ejecútalo sin instalar:

npx royalmail-mcp

Configuración

Obtén tu clave de API en Click & Drop → Settings → API credentials, luego configura:

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

Ya sea en un archivo .env junto al servidor, o a través de la configuración de tu cliente MCP (ver más abajo).

Claude Desktop

Añade a ~/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

Añade a ~/.cursor/mcp.json:

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

Servicios soportados

Además de otros 22, incluyendo variantes certificadas, servicios de verificación de edad y Parcelforce internacional. Ejecuta list_services para ver la lista completa.

Puedes pasar la clave amigable (first-class) o el código bruto del Registro de Servicios (OLP1). Ambos funcionan. Qué servicios puede usar tu cuenta depende de lo que esté habilitado en Click & Drop → Settings → Shipping services.

Limitaciones

Las etiquetas requieren una cuenta OBA

get_label solo funciona para clientes con una Online Business Account (OBA) de Royal Mail, la cuenta comercial facturada. Las cuentas estándar de pago por uso de Click & Drop recibirán 403 Forbidden (Feature not available) en get_label.

La reserva, el seguimiento y la cancelación funcionan en todos los tipos de cuenta. Si no tienes una OBA, aún puedes automatizar la creación de pedidos a través de este MCP y luego imprimir las etiquetas manualmente en la interfaz de usuario de Click & Drop.

Regístrate para OBA en auth.parcel.royalmail.com/register/oba.

Usuarios de OBA: habilitar auto-apply-postage

Si tienes una OBA, marca también "Apply postage automatically on orders imported via API" en Click & Drop → Settings. Sin esto, los pedidos permanecen como borradores y get_label devuelve "Label generation only available for orders with postage applied status".

Seguridad

Tu clave de API otorga acceso total a tu cuenta de Click & Drop. Trátala como una contraseña.

• Nunca subas .env a git. El .gitignore en este repositorio ya lo excluye.

• No pegues tu clave en mensajes de chat o documentos compartidos.

• Rótala en Click & Drop → Settings → API credentials si alguna vez se expone.

Privacidad y manejo de datos

Este MCP se ejecuta completamente en tu máquina. Ningún dato de cliente, credenciales o tráfico de API fluye a través de ningún servidor propiedad del autor u operado por él.

La ruta de los datos es:

• Los detalles de envío que le das a tu asistente de IA van a tu proveedor de IA (por ejemplo, Anthropic, si usas Claude) bajo tu cuenta.

• Las solicitudes de reserva van a Royal Mail Click & Drop usando tu clave de API.

• Las etiquetas se guardan en tu disco local en ~/Downloads/parcel-toolkit/ (se puede sobrescribir mediante la variable de entorno PARCEL_TOOLKIT_LABELS_DIR).

Si estás usando esto en una empresa del Reino Unido, eres el responsable del tratamiento de datos bajo el RGPD del Reino Unido. Recomendaciones prácticas:

1. Usa Claude Team, Claude Enterprise o la API de Claude directamente (no la versión de consumo Claude.ai) para que exista un Acuerdo de Procesamiento de Datos con Anthropic. En los niveles de consumo, desactiva "Help improve Claude" en la configuración de Privacidad como mínimo.

2. Incluye a Anthropic y Royal Mail como subprocesadores en tu política de privacidad, de la misma manera que incluirías a un proveedor de pagos o servicio de correo electrónico.

3. Evita usar esta herramienta para datos de categorías especiales (salud, biométricos, datos de menores) sin una revisión legal adicional.

4. Este software se proporciona tal cual bajo la licencia MIT. El autor no es un procesador de datos y no asume ninguna responsabilidad por tus obligaciones de cumplimiento; esas recaen sobre ti como responsable del tratamiento de datos.

Contribución

Los issues y pull requests son bienvenidos en github.com/catrinmdonnelly/royalmail-mcp. Si Royal Mail cambia su API, o encuentras un caso extremo en tu tipo de cuenta, por favor abre un issue con el cuerpo de la solicitud que enviaste y la respuesta que obtuviste (limpia tu clave de API primero).

MCP complementario

Para APC Overnight, consulta apc-mcp.

Descargo de responsabilidad

Este proyecto no está afiliado, respaldado ni patrocinado por Royal Mail Group Ltd. "Royal Mail", "Parcelforce" y "Click & Drop" son marcas comerciales de sus respectivos propietarios. Úsalo bajo tu propio riesgo.

Licencia

MIT. Ver LICENSE.