UPS MCP サーバー

UPS の配送・物流機能のための Model Context Protocol (MCP) サーバーです。このサーバーにより、AI システムが UPS API のツールとシームレスに統合できます。

ユーザーは MCP サーバーを統合することで、AI エージェントに代行して追跡イベントを処理させることができます。これには、荷物のステータス追跡、最新の輸送中画面、予定配達日時の確認が含まれます。エージェントは、UPS Developer Portal でアプリケーションを作成した後、ユーザーが提供する OAuth クライアント認証情報を使用して認証されます。

使用方法

前提条件

• Client ID と Client Secret を取得する: UPS Developer Portal でアプリケーションを作成し、OAuth 認証情報である Client ID と Client Secret を取得します。(https://developer.ups.com/get-started?loc=en_US)

• Python 3.12 以上

• uv (Python パッケージ) をインストールする

環境変数

• CLIENT_ID - UPS Client ID

• CLIENT_SECRET - UPS Client Secret

• ENVIRONMENT - テスト環境 (CIE) と本番環境のどちらを指すか (指定できる値: test、production)

注記: API 認証情報は機密情報です。バージョン管理にコミットしないでください。GitHub Secrets、ボールト、またはパスワードマネージャーを使用してシークレットを安全に管理することをお勧めします。

実行

uvx を使用してパッケージを実行できます:

uvx --from git+https://github.com/VoxveyAI/UPS-MCP ups-mcp

旧バージョンを使用するには、次のようにバージョン番号を指定できます:

uvx --from git+https://github.com/VoxveyAI/UPS-MCP@v1.0.0 ups-mcp

Related MCP server: UPS MCP Server

主な統合事例

以下は、主な統合のための設定ファイル例です。MCP クライアントによっては変更が必要な場合があります。

Claude Desktop

{
  "mcpServers": {
    "ups-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "git+https://github.com/VoxveyAI/UPS-MCP", "ups-mcp"],
      "env": {
        "CLIENT_ID": "**********",
        "CLIENT_SECRET": "**********",
        "ENVIRONMENT": "test"
      }
    }
  }
}

VS Code 内の GitHub Copilot

{
  "servers": {
    "ups-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "git+https://github.com/VoxveyAI/UPS-MCP", "ups-mcp"],
      "env": {
        "CLIENT_ID": "**********",
        "CLIENT_SECRET": "**********",
        "ENVIRONMENT": "test"
      }
    }
  }
}

利用可能なツール

サーバーは現在、中核となる国際配送ワークフローをサポートしています:

• validate_address — 米国およびプエルトリコの住所を検証します。UPS の 住所検証 API は一般的な国際住所バリデータではありません。国際配送先の データは配送/料金見積もりペイロードで提供されます。

• rate_shipment — UPS のサービスと料金を比較します。これは見積もりであり、 郵便料金を購入するものではありません。

• get_time_in_transit — 出発地、到着地、およびパッケージのリクエストに対する 輸送所要時間を推定します。

• get_customs_requirements — UPS が必要とする通関フィールドを取得します。

• validate_customs_details — 提供された通関データを検証します。

• estimate_landed_cost — UPS が返す関税、税金、およびその他の 総着地コストを推定します。

• create_shipment — 配送を作成し、UPS の配送/追跡および ラベルデータを返します。これには confirm=true が必要であり、 料金が発生する場合があります。

• recover_label — Shipping API コントラクトを使用してラベルを取得します。

• void_shipment — 配送を取り消します。confirm=true が必要です。

• rate_pickup — スケジュールを設定せずに集荷見積もりを取得します。

• create_pickup — 集荷をスケジュールします。confirm=true が必要です。

• get_pickup_status — アカウントの保留中集荷ステータスを確認します。

• cancel_pickup — 集荷をキャンセルします。confirm=true が必要です。

• find_pickup_service_centers — 集荷施設を検索します。

• get_pickup_political_divisions — 国に対して集荷可能な 行政区画を取得します。

• customs_description_guidance — action=start|continue|feedback を使用して、 Export Assure の対話型製品説明および商品/HTS ガイダンス セッションを開始、継続、またはフィードバックを送信します。

• submit_export_assure — コンプライアンスガイダンスのために 越境配送の詳細を送信します。

• upload_paperless_document, push_paperless_document_to_image_repository、および delete_paperless_document — UPS のペーパーレス通関/配送 明細を管理します。削除には confirm=true が必要です。

• lookup_dangerous_goods_chemical_reference および dangerous_goods_acceptance_precheck — 化学物質データを検索し、 UPS の危険物受入監査の事前チェックを実行します。

• get_delivery_intercept_options — action=eligibility|charges を使用して、 出荷後の配達変更の可否や料金を確認します。

• apply_delivery_intercept — action=redirect|willcall|return|reschedule を使用 して、輸送中の荷物の配送処理を変更します。confirm=true が必要です。

• cancel_delivery_intercept — 以前の割り込み（配達変更）リクエストをキャンセルします。 confirm=true が必要です。

• manage_tracking_alert_subscription — scope=package|account および action=subscribe|unsubscribe を使用して、永続的な Track Alert 型登録を管理します。confirm=true が必要です。

• messaging_setup_instruction — UPS Store、Access Point の場所、その他の 施設を見つけます。

• create_guaranteed_landed_cost_quote — UPS アカウントがその商品に アクセスできる場合に、保証付き着地費用の見積もりを要求します。

• track_package、track_by_reference、および track_shipment — 単一の荷物、 添付される参照の一致する荷物、および配送内のすべての荷物を追跡します。

複雑な UPS リクエスト本体は、../api-documentation 内のリクエストラッパーに 一致する検証済み JSON オブジェクトとして受け入れられます。これにより、 UPS 製品ごとに異なるバージョンに国内/国際の通関、サービス、パッケージング、 アカウントフィールドのサポートを維持しながら、共通の MCP 操作名を 大幅に変更することなくサポートできます。

配送の請求に関しては、accountNumber を create_shipment に渡すか、 リクエストラッパー内で相当する UPS フィールドを指定してください。 利便性のための引数は、以下に書き込まれます:

{
  "ShipmentRequest": {
    "Shipment": {
      "PaymentInformation": {
        "ShipmentCharge": {
          "BillShipper": {"AccountNumber": "YOUR_UPS_ACCOUNT_NUMBER"}
        }
      }
    }
  }
}

国際通関申告は、UPS の配送ラッパーの international-form フィールドで送信されます (また、validate_customs_details を通じて検証することもできます)。典型的な申告には、 平易な言語の説明、数量、単価、通貨、原産国、および既知の場合は調和度数コード が含われる 1 つ以上の製品/商品群が含まれます。申告するパッケージの価値は、 必要な場合にパッケージサービスオプションを介して個別に表されます。MCP は 建物コード、金額、原産国を推測しません。欠落している、または無効な通関 情報は、UPS が是正用として返します。

推奨される国際配送ワークフロー措置

1. rate_shipment と get_time_in_transit を呼び出します。

2. get_customs_requirements を呼び出し、次に validate_customs_details を呼びします。

3. estimate_landed_cost を呼び出し、返された関税、税金、および 警告を確認します。

4. 完全な配送ペイロードを確認し、配送物を実際に作成する場合のみ create_shipment を confirm=true 付きで呼び出します。

5. 返された追跡番号を track_package または track_shipment で追跡します。

6. 集荷は別途 create_pickup を confirm=true 付きでスケジュールします。

UPS API 製品の承認、アカウント権限、本番承認、サービス 利用可能性、国固有の適格性は UPS によって管理されます。 テスト環境での成功 した応答は、本番配送または集荷作成が有効であることを証明するものではありません。 アクティブになっていることを証明するものではありません。