royalmail-mcp

Claude, Cursor, Windsurf와 같은 MCP 호환 AI를 사용하여 Royal Mail 및 Parcelforce 배송을 예약, 라벨 생성, 추적 및 취소하세요.

라이브 Click & Drop API(2026년 4월 기준)에서 검증되었습니다. 예약, 추적 및 취소 기능은 엔드투엔드 테스트를 완료했습니다. 라벨 검색 기능은 OBA 계정 사양에 따라 검증되었습니다.

주요 기능

MCP를 지원하는 모든 AI에 6가지 도구를 제공합니다:

내부적으로는 사용자의 Click & Drop API 키를 사용하여 https://api.parcel.royalmail.com/api/v1과 통신합니다.

Related MCP server: UK Property Intelligence

프롬프트 예시

AI 클라이언트에 MCP가 설치되면 다음과 같이 요청할 수 있습니다:

"Alex Taylor(주소: 45 High Street, Manchester M1 1AA, 80g)에게 1st class letter를 예약해 줘. 참조 번호는 ORDER-1842로 해."

"이 세 가지 주문을 Tracked 48로 배송하고 orderIdentifier를 알려줘." (주소 목록 붙여넣기)

"이 주소로 £1,000 보상 조건의 Special Delivery by 1pm을 예약하고 라벨을 가져와."

"주문 1004를 취소해. 고객이 우편번호를 잘못 입력했어."

"500g 소포를 위한 가장 저렴한 등기 서비스가 뭐야?" (AI가 list_services를 호출하여 판단)

"주문 1002, 1003, 1004를 추적하고 각각의 상태를 요약해 줘."

"여기 10개의 주문이 있어. 모두 Royal Mail Tracked 24로 예약하고 인쇄할 수 있는 PDF 하나로 만들어 줘." (AI가 book_batch_and_label을 호출하고 병합된 PDF 경로를 반환)

AI가 주소 파싱, 서비스 선택 및 오류 복구를 처리합니다. 사용자는 비즈니스 결정만 내리면 됩니다.

비즈니스 워크플로우 아이디어

모든 AI 에이전트에 연결된 이 MCP는 실제 배송 운영을 자동화할 수 있습니다:

• 일일 주문 이행: 매일 아침 AI가 Shopify, WooCommerce 또는 스프레드시트에서 새 주문을 읽어 적절한 서비스 수준으로 Royal Mail 예약을 진행하고, 고객에게 운송장 번호를 전송합니다.

• 고객 서비스 대응: 고객이 "내 소포 어디에 있나요?"라고 문의하면 AI가 track_order를 호출하여 최신 상태를 요약하고 답변 초안을 작성합니다.

• 반품 처리: 고객이 반품을 요청하면 AI가 요청을 읽고 올바른 반품 서비스를 예약한 뒤, 인쇄 가능한 라벨을 즉시 이메일로 발송합니다.

• 복수 운송사 선택: apc-mcp와 함께 설치하면 AI가 예약 시점에 Royal Mail과 APC를 비교하여 목적지별로 가장 저렴하거나 빠른 옵션을 선택합니다.

• 대량 이행: 판매 이벤트나 구독 박스 발송 시 수백 개의 주문이 담긴 CSV를 AI에게 제공하면, 적절한 서비스와 보상 등급으로 한 번에 예약하고 요약본을 제공합니다.

• 결제 시 견적: 고객이 결제 단계에서 배송비를 문의하면 AI가 무게와 우편번호에 맞는 서비스를 선택하고 가격을 계산하여 즉시 응답합니다.

호환성

stdio 전송을 지원하는 모든 MCP 클라이언트와 호환됩니다:

• Claude Desktop

• Cursor

• Windsurf

• Claude Code

• Zed

ChatGPT, Smithery 및 기타 원격 전용 MCP 클라이언트는 HTTP 전송이 필요하며, 현재는 포함되어 있지 않습니다. 이 기능이 필요하다면 이슈를 열어주시면 우선순위를 조정하겠습니다.

설치

npm install -g royalmail-mcp

또는 설치 없이 실행:

npx royalmail-mcp

설정

Click & Drop → Settings → API credentials에서 API 키를 발급받은 후 다음을 설정하세요:

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"
      }
    }
  }
}

지원 서비스

등기 변형, 연령 확인 서비스, Parcelforce 국제 배송을 포함하여 22개 이상의 서비스가 추가로 지원됩니다. 전체 목록은 list_services를 실행하세요.

친숙한 키(first-class) 또는 원시 서비스 레지스터 코드(OLP1)를 모두 사용할 수 있습니다. 계정에서 사용할 수 있는 서비스는 Click & Drop → Settings → Shipping services 설정에 따라 다릅니다.

제한 사항

라벨 생성은 OBA 계정이 필요합니다

get_label은 Royal Mail OBA(Online Business Account), 즉 청구서 기반 비즈니스 계정 사용자에게만 작동합니다. 일반 Pay-as-you-go Click & Drop 계정은 get_label 호출 시 403 Forbidden (Feature not available) 오류가 발생합니다.

예약, 추적 및 취소는 모든 계정 유형에서 작동합니다. OBA가 없는 경우 이 MCP를 통해 주문 생성을 자동화한 후 Click & Drop UI에서 수동으로 라벨을 인쇄할 수 있습니다.

auth.parcel.royalmail.com/register/oba에서 OBA를 등록하세요.

OBA 사용자: 자동 우편 요금 적용 활성화

OBA 사용자인 경우 Click & Drop → Settings에서 **"Apply postage automatically on orders imported via API"**를 체크하세요. 그렇지 않으면 주문이 초안 상태로 유지되어 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 트래픽은 작성자가 소유하거나 운영하는 서버를 거치지 않습니다.

데이터 경로는 다음과 같습니다:

• AI 어시스턴트에게 제공하는 배송 정보는 사용자의 계정 하에 AI 제공업체(예: Claude 사용 시 Anthropic)로 전송됩니다.

• 예약 요청은 사용자의 API 키를 사용하여 Royal Mail Click & Drop으로 전송됩니다.

• 라벨은 로컬 디스크의 ~/Downloads/parcel-toolkit/에 저장됩니다(PARCEL_TOOLKIT_LABELS_DIR 환경 변수로 변경 가능).

영국 비즈니스에서 이 도구를 사용하는 경우, 귀하는 영국 GDPR에 따른 데이터 관리자입니다. 실무 권장 사항:

1. 소비자용 Claude.ai가 아닌 Claude Team, Claude Enterprise 또는 Claude API를 직접 사용하여 Anthropic과 데이터 처리 계약(DPA)이 체결되도록 하세요. 소비자 등급을 사용하는 경우 최소한 개인정보 설정에서 "Help improve Claude"를 끄십시오.

2. 결제 서비스나 이메일 서비스와 마찬가지로 개인정보 처리방침에 Anthropic과 Royal Mail을 하위 처리자로 명시하세요.

3. 추가적인 법적 검토 없이 민감한 데이터(건강, 생체 인식, 아동 데이터)에 이 도구를 사용하지 마세요.

4. 이 소프트웨어는 MIT 라이선스에 따라 있는 그대로 제공됩니다. 작성자는 데이터 처리자가 아니며 귀하의 규정 준수 의무에 대해 책임을 지지 않습니다. 해당 책임은 데이터 관리자인 귀하에게 있습니다.

기여

이슈 및 풀 리퀘스트는 github.com/catrinmdonnelly/royalmail-mcp에서 환영합니다. Royal Mail이 API를 변경하거나 계정 유형에서 예외적인 상황이 발생하면, 보낸 요청 본문과 받은 응답(API 키는 먼저 삭제)을 포함하여 이슈를 열어주세요.

관련 MCP

APC Overnight의 경우 apc-mcp를 참조하세요.

면책 조항

이 프로젝트는 Royal Mail Group Ltd와 제휴, 보증 또는 후원 관계가 아닙니다. "Royal Mail", "Parcelforce" 및 "Click & Drop"은 각 소유자의 상표입니다. 사용에 따른 책임은 사용자에게 있습니다.

라이선스

MIT. LICENSE를 참조하세요.