lob-mcp

Un servidor del Protocolo de Contexto de Modelo para la API de Lob.com. Permite que cualquier LLM compatible con MCP (Claude, etc.) verifique direcciones y envíe correo físico —postales, cartas, auto-enviables y cheques impresos— a través de Lob.

⚠️ Lob produce correo físico real y realiza cargos a su cuenta. Las herramientas de creación de piezas de correo (lob_postcards_create, lob_letters_create, lob_self_mailers_create, lob_checks_create, lob_*_orders_create) son facturables. Desarrolle con una clave de API test_…. Cambie a live_… solo cuando esté listo para enviar correo real. Pase siempre una idempotency_key para que los reintentos no dupliquen los envíos.

Características

• 76 herramientas en 12 grupos de recursos que cubren toda la superficie de la API v1 de Lob:

  • Libreta de direcciones (CRUD)

  • Verificación de direcciones en EE. UU. e internacionales (individual, masiva, autocompletado, geocodificación inversa, validación de identidad)

  • Postales, cartas, auto-enviables, cheques (crear, listar, recuperar, cancelar)

  • Plantillas y versiones de plantillas (CRUD)

  • Campañas y creatividades (CRUD)

  • Buckslips, tarjetas y sus órdenes de impresión

  • Campañas de Informed Delivery

  • Análisis de códigos QR

  • Pruebas de recursos (vista previa antes de enviar)

  • Cuentas bancarias (CRUD + verificación de microdepósitos)

  • Eventos de seguimiento de USPS

  • Suscripciones a webhooks (CRUD)

• Soporte de idempotencia en cada endpoint de creación facturable

• Detección de modo de prueba/producción a partir del prefijo de la clave de API, mostrada al inicio

• Redacción de PII — los campos de dirección se eliminan de la salida de errores

• Parámetro genérico extra en cada herramienta de creación/actualización — acepta cualquier parámetro de Lob no enumerado en el esquema, por lo que nunca se verá bloqueado por el retraso del SDK

Requisitos

• Node.js ≥ 18

• Una clave de API de Lob — obtenga una gratis en https://dashboard.lob.com/settings/api-keys

Instalación

Ejecutar mediante npx (sin instalación)

npx lob-mcp

Instalación global

npm install -g lob-mcp
lob-mcp

Instalación desde el código fuente

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

Configuración

El servidor se configura completamente a través de variables de entorno.

Uso con Claude Desktop

Agréguelo a su claude_desktop_config.json:

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

Reinicie Claude Desktop. Las herramientas de Lob deberían aparecer en el selector de herramientas.

Uso con Claude Code

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

Uso con el Inspector MCP

npm run inspector

Luego abra la URL impresa en su terminal. Establezca LOB_API_KEY en el panel de entorno del inspector antes de invocar las herramientas.

Referencia de herramientas

Todas las herramientas tienen el espacio de nombres lob_<recurso>_<acción>. Las sugerencias de anotación (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) se establecen según la especificación MCP para que los hosts puedan mostrar las solicitudes de confirmación adecuadas para operaciones facturables/destructivas.

Libreta de direcciones

• lob_addresses_create · lob_addresses_list · lob_addresses_get · lob_addresses_delete

Verificación de direcciones

• 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

Postales (facturables al crear)

• lob_postcards_create · lob_postcards_list · lob_postcards_get · lob_postcards_cancel

Cartas (facturables al crear)

• lob_letters_create · lob_letters_list · lob_letters_get · lob_letters_cancel

Auto-enviables (facturables al crear)

• lob_self_mailers_create · lob_self_mailers_list · lob_self_mailers_get · lob_self_mailers_cancel

Cheques (facturables al crear + retira fondos)

• lob_checks_create · lob_checks_list · lob_checks_get · lob_checks_cancel

Plantillas

• 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

Campañas + creatividades

• 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

Buckslips, tarjetas y órdenes de impresión (las órdenes son facturables)

• 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

Códigos QR + pruebas de recursos

• lob_qr_codes_list

• lob_resource_proofs_create · lob_resource_proofs_get · lob_resource_proofs_update

Cuentas bancarias (necesarias para emitir cheques)

• lob_bank_accounts_create · lob_bank_accounts_list · lob_bank_accounts_get · lob_bank_accounts_delete · lob_bank_accounts_verify

Eventos de seguimiento

• lob_tracking_events_list

Webhooks

• lob_webhooks_create · lob_webhooks_list · lob_webhooks_get · lob_webhooks_update · lob_webhooks_delete

Modelo de seguridad

Este servidor aplica tres prácticas de seguridad apropiadas para una API de dinero real:

1. Detección de modo de prueba/producción. El servidor inspecciona el prefijo de su clave de API al inicio y registra el modo activo en stderr. Una clave test_… no produce correo real; una clave live_… produce correo real y facturable.

2. Idempotencia. Cada herramienta de creación facturable expone un parámetro opcional idempotency_key. Pase un UUID (o cualquier cadena única de hasta 256 caracteres) por solicitud lógica. Lob devolverá la respuesta original para cualquier solicitud posterior que reutilice la misma clave, evitando correo duplicado en reintentos de red.

3. Redacción de PII en errores. Los campos de dirección, nombre y contacto se eliminan de cualquier carga útil de error que se devuelva al cliente. El cuerpo completo de la solicitud nunca se registra; solo se muestra metadatos de error (estado, código, ID de solicitud, mensaje).

La trampilla de escape extra

La API de Lob tiene muchas opciones específicas de recursos que no vale la pena enumerar en un esquema de herramienta (IDs de sobre personalizados, páginas de perforación, grupos de facturación, indicadores de marketing, etc.). Cada herramienta de creación/actualización acepta un objeto extra opcional cuyas claves se fusionan literalmente en el cuerpo de la solicitud:

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

Consulte https://docs.lob.com/ para obtener el conjunto completo de parámetros por recurso.

Desarrollo

npm install
npm run build
npm run typecheck
npm run inspector

La salida compilada reside en build/. El código fuente está en src/.

Arquitectura

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

El cliente HTTP es intencionalmente ligero — no depende del lob-typescript-sdk oficial, lo que mantiene la superficie de dependencias pequeña y le da a este servidor un control más estricto sobre los encabezados, los reintentos y el manejo de PII. Se pueden agregar nuevos endpoints de Lob registrando una herramienta más en el archivo del grupo de recursos (o mediante la trampilla de escape extra en las herramientas existentes).

Limitaciones

• Cargas de archivos multipart para recursos que aceptan bytes binarios de PDF/imagen son compatibles con el cliente subyacente (asForm: true) pero aún no están expuestas en ninguna herramienta — las herramientas actuales aceptan cadenas HTML, URLs, IDs de plantilla y URIs de datos en base64, lo que cubre las formas de origen de contenido documentadas de Lob.

• OAuth no es compatible porque Lob no lo ofrece; la autenticación es HTTP Basic con una clave de API, según la documentación de Lob.

Contribuciones

Las incidencias y solicitudes de extracción son bienvenidas en https://github.com/optimize-overseas/lob-mcp.

Licencia

MIT — ver LICENSE.

Descargo de responsabilidad

Este proyecto no está afiliado, respaldado ni patrocinado por Lob.com. "Lob" es una marca comercial de Lob.com, Inc. El uso de la API de Lob está sujeto a los Términos de servicio y a la Política de uso aceptable de Lob.