lob-mcp

一个用于 Lob.com API 的 模型上下文协议 (Model Context Protocol) 服务器。允许任何兼容 MCP 的 LLM（如 Claude 等）通过 Lob 验证地址并发送实体邮件——包括明信片、信件、自助邮寄件和打印支票。

⚠️ Lob 会产生真实的实体邮件并向您的账户收费。 邮件创建工具（lob_postcards_create、lob_letters_create、lob_self_mailers_create、lob_checks_create、lob_*_orders_create）是收费的。请使用 test_… API 密钥进行开发。仅在准备好发送真实邮件时切换到 live_… 密钥。请务必传递 idempotency_key（幂等键），以防止重试导致重复发送。

功能

• 76 种工具，涵盖 12 个资源组，覆盖完整的 Lob v1 API 表面：

  • 地址簿 (CRUD)

  • 美国及国际地址验证（单条、批量、自动补全、反向地理编码、身份验证）

  • 明信片、信件、自助邮寄件、支票（创建、列出、检索、取消）

  • 模板和模板版本 (CRUD)

  • 营销活动和创意 (CRUD)

  • 夹页、卡片及其打印订单

  • Informed Delivery 营销活动

  • 二维码分析

  • 资源预览（发送前预览）

  • 银行账户 (CRUD + 微存款验证)

  • USPS 追踪事件

  • Webhook 订阅 (CRUD)

• 每个收费创建端点均支持 幂等性

• 从 API 密钥前缀检测 测试/生产模式，并在启动时显示

• PII 脱敏 — 地址字段会从错误输出中剔除

• 每个创建/更新工具上都有通用的 extra 参数 — 接受模式中未枚举的任何 Lob 参数，因此您永远不会因为 SDK 滞后而受阻

要求

• Node.js ≥ 18

• Lob API 密钥 — 可在 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。在调用工具之前，请在 Inspector 的环境面板中设置 LOB_API_KEY。

工具参考

所有工具的命名空间均为 lob_<resource>_<action>。注释提示（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

二维码 + 资源预览

• 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

Webhooks

• 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 脱敏。 地址、姓名和联系字段会从回传给客户端的任何错误负载中剔除。完整的请求体永远不会被记录；仅显示错误元数据（状态、代码、请求 ID、消息）。

extra 逃生舱

Lob 的 API 有许多资源特定的选项，不值得在工具模式中一一枚举（自定义信封 ID、穿孔页、计费组、营销标志等）。每个创建/更新工具都接受一个可选的 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 处理。可以通过在资源组文件中注册更多工具（或通过现有工具上的 extra 逃生舱）来添加新的 Lob 端点。

限制

• 多部分文件上传：对于接受二进制 PDF/图像字节的资源，底层客户端支持（asForm: true），但尚未在任何工具中公开 — 当前工具接受 HTML 字符串、URL、模板 ID 和 base64 数据 URI，这涵盖了已记录的 Lob 内容源格式。

• OAuth：不支持，因为 Lob 不提供此功能；根据 Lob 的文档，身份验证是使用 API 密钥的 HTTP Basic 认证。

贡献

欢迎在 https://github.com/optimize-overseas/lob-mcp 提交问题和拉取请求。

许可证

MIT — 参见 LICENSE。

免责声明

本项目不隶属于 Lob.com，也不受其认可或赞助。“Lob”是 Lob.com, Inc. 的商标。使用 Lob API 须遵守 Lob 的 服务条款 和 可接受使用政策。