UPS MCP 서버

MIT License Node.js 20+ MCP TypeScript npm

UPS 배송 및 물류 API를 위한 Model Context Protocol 서버입니다. AI 에이전트가 배송 생성, 패키지 추적, 요금 조회, 주소 검증, 픽업 예약 및 UPS 위치 찾기를 수행할 수 있도록 합니다.

빠른 설치

MCP 설정(~/.cursor/mcp.json, .cursor/mcp.json 또는 claude_desktop_config.json)에 추가하세요:

{
  "mcpServers": {
    "ups": {
      "command": "npx",
      "args": ["-y", "ups-mcp"],
      "env": {
        "UPS_CLIENT_ID": "your_client_id",
        "UPS_CLIENT_SECRET": "your_client_secret",
        "UPS_ACCOUNT_NUMBER": "123456",
        "UPS_ENVIRONMENT": "sandbox"
      }
    }
  }
}

UPS 개발자 포털에서 자격 증명을 받으세요.

도구

도구	설명
`create_shipment`	배송을 생성하고 배송 라벨을 생성합니다
`void_shipment`	배송을 취소하고 라벨을 무효화합니다
`track_package`	전체 활동 내역과 함께 패키지를 추적합니다
`get_rates`	사용 가능한 모든 서비스에 대한 배송 요금을 조회합니다
`get_time_in_transit`	예상 배송 날짜를 조회합니다
`validate_address`	미국/푸에르토리코 주소를 검증합니다
`schedule_pickup`	패키지 픽업을 예약합니다
`cancel_pickup`	예약된 픽업을 취소합니다
`find_locations`	근처 UPS 매장 및 드롭오프 지점을 찾습니다

사전 요구 사항

Node.js 20+
UPS 개발자 포털 자격 증명 (시작하기)
UPS 계정 번호 (배송 및 요금 조회용)

설치

npx ups-mcp

또는 전역으로 설치:

npm install -g ups-mcp

설정

환경 변수

변수	필수	설명
`UPS_CLIENT_ID`	예	UPS 개발자 포털의 OAuth 클라이언트 ID
`UPS_CLIENT_SECRET`	예	OAuth 클라이언트 시크릿
`UPS_ENVIRONMENT`	아니요	`sandbox` (기본값) 또는 `production`
`UPS_ACCOUNT_NUMBER`	아니요	6자리 UPS 계정 (배송/요금 조회 시 필수)

클라이언트	설정 파일
Cursor (프로젝트)	`.cursor/mcp.json`
Cursor (전역)	`~/.cursor/mcp.json`
Claude Desktop	`claude_desktop_config.json`
VS Code	`.vscode/mcp.json`

사용 예시

배송 생성

"UPS Ground를 통해 123 Main St, Atlanta GA 30301에서 456 Oak Ave, Los Angeles CA 90001로 5lb 패키지를 배송해줘"

요금 조회

"NYC에서 Chicago로 보내는 10lb 패키지의 배송 요금은 얼마인가요?"

패키지 추적

"패키지 1Z999AA10123456784 추적해줘"

주소 검증

"1600 Pennsylvania Ave NW, Washington DC 20500은 유효한 주소인가요?"

픽업 예약

"내일 오전 9시에 우리 창고에서 패키지 3개 픽업 예약해줘"

개발

git clone https://github.com/roscoej/ups-mcp.git
cd ups-mcp
npm install
npm run build

MCP Inspector로 테스트

npm run inspector

로컬 실행

cp .env.example .env
# Edit .env with your credentials
npm run build
node dist/index.js

아키텍처

src/
├── index.ts            # Entry point (stdio transport)
├── config.ts           # Environment variable resolution
├── server.ts           # MCP server factory
├── client/
│   ├── auth.ts         # OAuth 2.0 token manager
│   ├── http.ts         # HTTP client with retry + error handling
│   └── errors.ts       # Structured error types
├── tools/
│   ├── tracking.ts     # track_package
│   ├── shipping.ts     # create_shipment, void_shipment
│   ├── rating.ts       # get_rates, get_time_in_transit
│   ├── address.ts      # validate_address
│   ├── pickup.ts       # schedule_pickup, cancel_pickup
│   ├── locator.ts      # find_locations
│   ├── builders.ts     # Shared request payload builders
│   ├── constants.ts    # UPS API codes and enumerations
│   └── schemas.ts      # Zod input schemas
└── types/
    ├── config.ts       # Server configuration
    ├── shipping.ts     # Shipment types + service codes
    ├── tracking.ts     # Tracking types
    ├── rating.ts       # Rating types
    ├── address.ts      # Address validation types
    └── pickup.ts       # Pickup types

보안

API 자격 증명은 민감한 정보입니다. 버전 관리 시스템에 절대 커밋하지 마세요. 환경 변수나 보안 관리자를 사용하세요.

면책 조항

이 프로젝트는 독립적이고 비공식적인 제3자 도구입니다. United Parcel Service, Inc.(UPS) 또는 그 자회사와 공식적으로 관련이 없으며, 보증, 후원 또는 승인되지 않았습니다.

"UPS" 및 UPS 브랜드 마크는 United Parcel Service of America, Inc.의 등록 상표입니다. 기타 모든 상표는 각 소유자의 자산입니다. 이러한 이름의 사용은 식별 및 상호 운용성 목적일 뿐이며 보증을 의미하지 않습니다.

이 소프트웨어는 어떠한 종류의 보증 없이 "있는 그대로" 제공됩니다. 귀하는 다음 사항에 대해 전적인 책임을 집니다:

UPS 기술 계약 및 모든 관련 UPS 서비스 약관, 요금 제한 및 허용 가능한 사용 정책 준수.
API 자격 증명 및 UPS 계정 보안 유지.
이 도구를 통해 귀하의 UPS 계정에서 수행되는 모든 활동.
귀하의 관할 구역 내 모든 관련 법률 및 규정 준수.

저자와 기여자는 이 소프트웨어 또는 이를 통해 액세스되는 UPS API 사용으로 인해 발생하는 손해에 대해 어떠한 책임도 지지 않습니다.

기여

기여를 환영합니다! 가이드라인은 CONTRIBUTING.md를 참조하세요.

라이선스

MIT

UPS MCP Server