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를 전달하세요.

기능

• 12개 리소스 그룹에 걸친 76개의 도구로 Lob v1 API 전체를 지원:

  • 주소록 (CRUD)

  • 미국 및 국제 주소 확인 (단일, 대량, 자동 완성, 역지오코딩, 신원 확인)

  • 엽서, 편지, 셀프 메일러, 수표 (생성, 목록 조회, 상세 조회, 취소)

  • 템플릿 및 템플릿 버전 (CRUD)

  • 캠페인 및 크리에이티브 (CRUD)

  • 벅슬립(Buckslips), 카드 및 인쇄 주문

  • Informed Delivery 캠페인

  • QR 코드 분석

  • 리소스 증명 (발송 전 미리보기)

  • 은행 계좌 (CRUD + 소액 입금 확인)

  • USPS 추적 이벤트

  • 웹훅 구독 (CRUD)

• 모든 유료 생성 엔드포인트에 대한 멱등성(Idempotency) 지원

• 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_<리소스>_<작업> 네임스페이스를 사용합니다. 주석 힌트(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 마스킹. 주소, 이름 및 연락처 필드는 클라이언트로 반환되는 모든 오류 페이로드에서 제거됩니다. 전체 요청 본문은 절대 기록되지 않으며, 오류 메타데이터(상태, 코드, 요청 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 처리를 더 엄격하게 제어할 수 있습니다. 새로운 Lob 엔드포인트는 리소스 그룹 파일에 도구를 하나 더 등록하거나 기존 도구의 extra 탈출구를 통해 추가할 수 있습니다.

제한 사항

• 바이너리 PDF/이미지 바이트를 허용하는 리소스에 대한 멀티파트 파일 업로드는 기본 클라이언트(asForm: true)에서 지원되지만 아직 도구로 노출되지 않았습니다. 현재 도구는 HTML 문자열, URL, 템플릿 ID 및 base64 데이터 URI를 허용하며, 이는 문서화된 Lob 콘텐츠 소스 형식을 모두 포함합니다.

• Lob에서 제공하지 않으므로 OAuth는 지원되지 않습니다. 인증은 Lob 문서에 따라 API 키를 사용하는 HTTP Basic 인증입니다.

기여

이슈 및 풀 리퀘스트는 https://github.com/optimize-overseas/lob-mcp에서 환영합니다.

라이선스

MIT — LICENSE를 참조하세요.

면책 조항

이 프로젝트는 Lob.com과 제휴, 보증 또는 후원 관계가 아닙니다. "Lob"은 Lob.com, Inc.의 상표입니다. Lob API 사용은 Lob의 서비스 약관 및 허용 가능한 사용 정책을 따릅니다.