lob-mcp

Сервер Model Context Protocol для API Lob.com. Позволяет любой LLM, совместимой с MCP (Claude и др.), проверять адреса и отправлять физическую почту — открытки, письма, саморассылки и печатные чеки — через Lob.

⚠️ Lob создает реальную физическую почту и списывает средства с вашего счета. Инструменты создания почтовых отправлений (lob_postcards_create, lob_letters_create, lob_self_mailers_create, lob_checks_create, lob_*_orders_create) являются платными. Разрабатывайте с использованием API-ключа test_…. Переключайтесь на live_… только тогда, когда будете готовы к отправке реальной почты. Всегда передавайте idempotency_key, чтобы повторные попытки не приводили к дублированию отправлений.

Функции

• 76 инструментов в 12 группах ресурсов, охватывающих всю поверхность API Lob v1:

  • Адресная книга (CRUD)

  • Проверка адресов в США и международных (единичная, массовая, автозаполнение, обратное геокодирование, проверка личности)

  • Открытки, письма, саморассылки, чеки (создание, список, получение, отмена)

  • Шаблоны и версии шаблонов (CRUD)

  • Кампании и креативы (CRUD)

  • Вкладыши, карточки и заказы на их печать

  • Кампании Informed Delivery

  • Аналитика QR-кодов

  • Подтверждения ресурсов (предварительный просмотр перед отправкой)

  • Банковские счета (CRUD + проверка микродепозитов)

  • События отслеживания USPS

  • Подписки на вебхуки (CRUD)

• Поддержка идемпотентности для каждого платного эндпоинта создания

• Определение тестового/рабочего режима по префиксу API-ключа, отображается при запуске

• Редактирование PII — поля адреса удаляются из вывода ошибок

• Универсальный параметр extra для каждого инструмента создания/обновления — принимает любой параметр Lob, не перечисленный в схеме, поэтому вы никогда не будете заблокированы из-за отставания SDK

Требования

• Node.js ≥ 18

• API-ключ Lob — получите бесплатно на https://dashboard.lob.com/settings/api-keys

Установка

Запуск через npx (без установки)

npx lob-mcp

Глобальная установка

npm install -g lob-mcp
lob-mcp

Установка из исходного кода

git clone https://github.com/optimize-overseas/lob-mcp.git
cd lob-mcp
npm install
npm run build
node build/index.js

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

Сервер полностью настраивается через переменные окружения.

Использование с Claude Desktop

Добавьте в ваш claude_desktop_config.json:

{
  "mcpServers": {
    "lob": {
      "command": "npx",
      "args": ["-y", "lob-mcp"],
      "env": {
        "LOB_API_KEY": "test_your_key_here"
      }
    }
  }
}

Перезапустите Claude Desktop. Инструменты Lob должны появиться в меню выбора инструментов.

Использование с Claude Code

claude mcp add lob --env LOB_API_KEY=test_your_key_here -- npx -y lob-mcp

Использование с MCP Inspector

npm run inspector

Затем откройте URL, выведенный в терминале. Установите LOB_API_KEY на панели окружения инспектора перед вызовом инструментов.

Справочник инструментов

Все инструменты имеют пространство имен lob_<ресурс>_<действие>. Подсказки аннотаций (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) установлены согласно спецификации MCP, чтобы хосты могли отображать соответствующие запросы подтверждения для платных/деструктивных операций.

Адресная книга

• lob_addresses_create · lob_addresses_list · lob_addresses_get · lob_addresses_delete

Проверка адресов

• lob_us_verifications_create · lob_us_verifications_get

• lob_us_autocompletions_create

• lob_intl_verifications_create

• lob_bulk_us_verifications_create · lob_bulk_intl_verifications_create

• lob_reverse_geocode

• lob_identity_validation

Открытки (оплата при создании)

• lob_postcards_create · lob_postcards_list · lob_postcards_get · lob_postcards_cancel

Письма (оплата при создании)

• lob_letters_create · lob_letters_list · lob_letters_get · lob_letters_cancel

Саморассылки (оплата при создании)

• lob_self_mailers_create · lob_self_mailers_list · lob_self_mailers_get · lob_self_mailers_cancel

Чеки (оплата при создании + списание средств)

• lob_checks_create · lob_checks_list · lob_checks_get · lob_checks_cancel

Шаблоны

• lob_templates_create · lob_templates_list · lob_templates_get · lob_templates_update · lob_templates_delete

• lob_template_versions_create · lob_template_versions_list · lob_template_versions_get · lob_template_versions_update · lob_template_versions_delete

Кампании + креативы

• lob_campaigns_create · lob_campaigns_list · lob_campaigns_get · lob_campaigns_update · lob_campaigns_delete

• lob_creatives_create · lob_creatives_list · lob_creatives_get · lob_creatives_update · lob_creatives_delete

Вкладыши, карточки и заказы на печать (заказы платные)

• lob_buckslips_create · lob_buckslips_list · lob_buckslips_get

• lob_buckslip_orders_create · lob_buckslip_orders_list

• lob_cards_create · lob_cards_list · lob_cards_get

• lob_card_orders_create · lob_card_orders_list

Informed Delivery

• lob_informed_delivery_campaigns_create · lob_informed_delivery_campaigns_list · lob_informed_delivery_campaigns_get

QR-коды + подтверждения ресурсов

• lob_qr_codes_list

• lob_resource_proofs_create · lob_resource_proofs_get · lob_resource_proofs_update

Банковские счета (необходимы для выписки чеков)

• lob_bank_accounts_create · lob_bank_accounts_list · lob_bank_accounts_get · lob_bank_accounts_delete · lob_bank_accounts_verify

События отслеживания

• lob_tracking_events_list

Вебхуки

• lob_webhooks_create · lob_webhooks_list · lob_webhooks_get · lob_webhooks_update · lob_webhooks_delete

Модель безопасности

Этот сервер применяет три практики безопасности, соответствующие API с реальными деньгами:

1. Определение тестового/рабочего режима. Сервер проверяет префикс вашего API-ключа при запуске и записывает активный режим в stderr. Ключ test_… не создает реальную почту; ключ live_… создает реальную, платную почту.

2. Идемпотентность. Каждый платный инструмент создания предоставляет необязательный параметр idempotency_key. Передавайте UUID (или любую уникальную строку до 256 символов) для каждого логического запроса. Lob вернет исходный ответ для любого последующего запроса с тем же ключом, предотвращая дублирование почты при повторных попытках сети.

3. Редактирование PII в ошибках. Поля адреса, имени и контактные данные удаляются из любого полезного содержимого ошибки, возвращаемого клиенту. Полное тело запроса никогда не логируется; отображаются только метаданные ошибки (статус, код, идентификатор запроса, сообщение).

«Лазейка» extra

API Lob имеет множество специфичных для ресурсов опций, которые не стоит перечислять в схеме инструмента (пользовательские идентификаторы конвертов, страницы перфорации, биллинговые группы, маркетинговые флаги и т. д.). Каждый инструмент создания/обновления принимает необязательный объект extra, ключи которого объединяются дословно с телом запроса:

{
  "to": "adr_123…",
  "from": "adr_456…",
  "front": "<html>…</html>",
  "back": "<html>…</html>",
  "extra": {
    "billing_group_id": "bg_…",
    "use_type": "marketing"
  }
}

Обратитесь к https://docs.lob.com/ для получения полного набора параметров для каждого ресурса.

Разработка

npm install
npm run build
npm run typecheck
npm run inspector

Скомпилированный вывод находится в build/. Исходный код — в src/.

Архитектура

src/
├── index.ts            # stdio entry — boots McpServer + LobClient
├── env.ts              # env loading + test/live mode detection
├── lob/
│   ├── client.ts       # fetch-based HTTP client (Basic auth, idempotency, errors)
│   ├── errors.ts       # LobApiError + tool-friendly formatter
│   └── redact.ts       # PII redaction
├── schemas/
│   ├── common.ts       # address, pagination, idempotency, metadata schemas
│   └── mail.ts         # mail-piece-shared schemas
└── tools/
    ├── helpers.ts      # registerTool helper with consistent error mapping
    ├── register.ts     # wires every group into the server
    └── *.ts            # one file per resource group

HTTP-клиент намеренно сделан легким — он не зависит от официального lob-typescript-sdk, что сохраняет поверхность зависимостей небольшой и дает этому серверу более жесткий контроль над заголовками, повторными попытками и обработкой PII. Новые эндпоинты Lob можно добавить, зарегистрировав еще один инструмент в файле группы ресурсов (или через «лазейку» extra в существующих инструментах).

Ограничения

• Многочастная загрузка файлов для ресурсов, принимающих байты PDF/изображений, поддерживается базовым клиентом (asForm: true), но пока не представлена ни в одном инструменте — текущие инструменты принимают строки HTML, URL-адреса, идентификаторы шаблонов и URI данных base64, что охватывает задокументированные формы источников контента Lob.

• OAuth не поддерживается, так как Lob его не предлагает; аутентификация — HTTP Basic с API-ключом, согласно документации Lob.

Участие

Вопросы и pull-запросы приветствуются на https://github.com/optimize-overseas/lob-mcp.

Лицензия

MIT — см. LICENSE.

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

Этот проект не связан, не одобрен и не спонсируется Lob.com. "Lob" является торговой маркой Lob.com, Inc. Использование API Lob регулируется Условиями обслуживания и Политикой допустимого использования Lob.