royalmail-mcp

Оформляйте, маркируйте, отслеживайте и отменяйте отправления Royal Mail и Parcelforce с помощью любого ИИ, совместимого с MCP, такого как Claude, Cursor или Windsurf.

Проверено на рабочем API Click & Drop (апрель 2026 г.). Бронирование, отслеживание и отмена протестированы от начала до конца. Получение этикеток проверено на соответствие спецификации для учетных записей OBA.

Что он делает

Предоставляет шесть инструментов любому ИИ, который поддерживает протокол MCP:

В фоновом режиме он взаимодействует с https://api.parcel.royalmail.com/api/v1, используя ваш API-ключ Click & Drop.

Related MCP server: UK Property Intelligence

Примеры запросов

После установки MCP в вашем ИИ-клиенте вы можете использовать такие запросы:

"Оформи заказ на письмо 1-го класса для Алекса Тейлора, 45 High Street, Манчестер M1 1AA, 80 грамм. Присвой номер ORDER-1842."

"Отправь эти три заказа через Tracked 48 и дай мне их orderIdentifiers." (вставьте список адресов)

"Оформи Special Delivery к 13:00 с компенсацией £1,000 на этот адрес, затем получи этикетку."

"Отмени заказ 1004. Клиент указал неверный почтовый индекс."

"Какая самая дешевая служба с подтверждением получения для посылки весом 500 г?" (ИИ вызывает list_services и анализирует)

"Отследи заказы 1002, 1003 и 1004 и кратко опиши, где находится каждый из них."

"Вот десять заказов — оформи их все через Royal Mail Tracked 24 и дай мне один PDF-файл для печати." (ИИ вызывает book_batch_and_label и возвращает путь к объединенному PDF-файлу.)

ИИ берет на себя разбор адресов, выбор службы и обработку ошибок. Вы принимаете бизнес-решения.

Идеи рабочих процессов для бизнеса

Будучи подключенным к любому ИИ-агенту, этот MCP может автоматизировать реальные операции по доставке:

• Ежедневное выполнение заказов. Каждое утро ваш ИИ считывает новые заказы из Shopify, WooCommerce или электронной таблицы, оформляет каждый из них через Royal Mail с нужным уровнем обслуживания и отправляет номера для отслеживания обратно клиенту.

• Сортировка запросов в службу поддержки. Когда клиент пишет "где моя посылка?", ваш ИИ вызывает track_order, резюмирует последний статус простым языком и составляет черновик ответа.

• Обработка возвратов. Клиент запрашивает возврат. Ваш ИИ считывает запрос, бронирует правильную службу возврата и отправляет этикетку для печати прямо клиенту, без участия сотрудников.

• Выбор перевозчика. При установке вместе с apc-mcp, ваш ИИ сравнивает Royal Mail и APC во время оформления заказа и выбирает самый дешевый или быстрый вариант для каждого пункта назначения.

• Дни массовой обработки заказов. Для распродаж или рассылок по подписке дайте вашему ИИ CSV-файл с сотнями заказов. Он оформит их все с нужным уровнем обслуживания и компенсации за один проход, а затем предоставит вам сводку.

• Расчет стоимости при оформлении. Когда клиент спрашивает стоимость доставки при оформлении заказа, ваш ИИ выбирает подходящую службу для веса и почтового индекса, рассчитывает цену и отвечает в течение нескольких секунд.

Совместимость

Работает с любым MCP-клиентом, поддерживающим транспорт stdio:

• Claude Desktop

• Cursor

• Windsurf

• Claude Code

• Zed

ChatGPT, Smithery и другие удаленные MCP-клиенты требуют HTTP-транспорт, который пока не включен. Если это важно для вас, откройте issue, чтобы я мог расставить приоритеты.

Установка

npm install -g royalmail-mcp

Или запустите без установки:

npx royalmail-mcp

Конфигурация

Получите свой API-ключ в Click & Drop → Settings → API credentials, затем установите:

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 работает только для клиентов с учетной записью Royal Mail Online Business Account (OBA), то есть с бизнес-аккаунтом с оплатой по счету. Стандартные аккаунты Click & Drop с оплатой по факту получат ошибку 403 Forbidden (Feature not available) при вызове get_label.

Бронирование, отслеживание и отмена работают для всех типов учетных записей. Если у вас нет OBA, вы все равно можете автоматизировать создание заказа через этот MCP, а затем распечатать этикетки вручную в интерфейсе Click & Drop.

Зарегистрируйтесь в OBA на auth.parcel.royalmail.com/register/oba.

Пользователи OBA: включите автоматическое применение почтовых сборов

Если вы используете OBA, также установите галочку "Apply postage automatically on orders imported via API" в Click & Drop → Settings. Без этого заказы остаются черновиками, и 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-трафик не проходят через серверы, принадлежащие или управляемые автором.

Путь данных:

• Сведения о доставке, которые вы предоставляете своему ИИ-помощнику, отправляются вашему поставщику ИИ (например, Anthropic, если вы используете Claude) под вашей учетной записью.

• Запросы на бронирование отправляются в Royal Mail Click & Drop с использованием вашего API-ключа.

• Этикетки сохраняются на вашем локальном диске в ~/Downloads/parcel-toolkit/ (можно изменить через переменную окружения PARCEL_TOOLKIT_LABELS_DIR).

Если вы используете это в британском бизнесе, вы являетесь контролером данных в соответствии с UK GDPR. Практические рекомендации:

1. Используйте Claude Team, Claude Enterprise или API Claude напрямую — не потребительскую версию Claude.ai — чтобы было заключено Соглашение об обработке данных (DPA) с Anthropic. В потребительских версиях как минимум отключите "Help improve Claude" в настройках конфиденциальности.

2. Укажите Anthropic и Royal Mail в качестве субпроцессоров в своей политике конфиденциальности, так же, как вы бы указали платежного провайдера или почтовый сервис.

3. Избегайте использования этого инструмента для данных специальных категорий (здоровье, биометрия, данные детей) без дополнительной юридической проверки.

4. Это программное обеспечение предоставляется "как есть" по лицензии MIT. Автор не является обработчиком данных и не несет ответственности за ваши обязательства по соблюдению нормативных требований — они лежат на вас как на контролере данных.

Участие в разработке

Вопросы и pull-запросы приветствуются на github.com/catrinmdonnelly/royalmail-mcp. Если Royal Mail изменит свой API или вы столкнетесь с пограничным случаем в своем типе учетной записи, пожалуйста, откройте issue с телом запроса, который вы отправили, и полученным ответом (сначала удалите свой API-ключ).

Сопутствующий MCP

Для APC Overnight см. apc-mcp.

Отказ от ответственности

Этот проект не связан, не одобрен и не спонсируется Royal Mail Group Ltd. "Royal Mail", "Parcelforce" и "Click & Drop" являются товарными знаками соответствующих владельцев. Используйте на свой страх и риск.

Лицензия

MIT. См. LICENSE.