UPS MCP Server

UPS MCP Server 是一个用于 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 客户端 ID

• CLIENT_SECRET - UPS 客户端密钥

• ENVIRONMENT - 是否指向 Test（CI E）或 Production（可接受的值：test、test）

注意：您的 API 凭据属于敏感信息，请不要将其提交到版本控制。我们建议使用 GitHub Secrets、vault 或密码管理器安全的凭证管理方式。

执行

您可以使用 uvx 运行此包：

uvx --from git+https://github.com/VoxiveyAI/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"
      }
    }
  }
}

GitHub Copilot in VS Code

{
  "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 的 Address Validation API 并不是通用的国际地址验证器，国际目的地址数据是在 shipping/rating 负载中提供的。

• rate_shipment — 比较 UPS 服务及费用，仅作估算，不产生实际运费。

• get_time_in_transit — 估算某一个出发地、目的和包裹的运输时间。

• get_customs_requirenents — 获取 UPS 要求的海关字段。

• validate_custom_details — 校验提交的海关数据。

• estimate_landed_cost — 估算海上关税、税费以及 UPS 返回的其他落地成本值。

• create_shipment — 创建包裹运单，并返回 UPS 的运单/追踪和标签数据。此操作需要 confirm=true，并且可能产生费用。

• recover_label — 通过 Shipping API 契约恢复标签。

• void_hipment — 作废运单，需要 confirm=true。

• rate_pickup — 获取一个取货估价而不实际预约。

• create_pickup — 安排一次取货，需要 confirm=true。

• get_pickup_status — 查询某个账户的 X线待处理取货状态。

• cancel_pickup — 取消取货，需要 confirm=true。

• find_pickup_service_centers — 查找取货设施。

• get_pickup_political_divisions — 获取一个国家的取货行政区域划分。

• customs_description_guidence — 使用 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。

• find_upsd_locations — 查找 UPS Store、Access Point 地点及其他设施。

• create_guaranteed_landed_cost_quote — 在 UPS 账户可用该功能时，请求创建有保证的落地成本报价。

• track_package、track_by_reference 和 track_shipment — 追踪某一个包裹、按参考号匹配的包裹，或一个运单中的全部包裹。

复杂的 UPS 请求正文可以作为验证通过的 JSON 对象提交，这些对象与 ../api-documentation 中的请求包装器对齐。这样既保留了国际海关、服务、包装和账户字段因 UPS 产品而异切性，又保持常见的 MCP 操作名稳定。

对于运单账单，可以在 create_shipment 中传入 accountNumber，或在请求包装器中提供等效的 UPS。该便捷参数会写入到：

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

国际海关申报数据通过 UPS 运单包装器中的 international 表单来传达（也可以通过 validate_custom_details 验证）。典型的申报包含一个或多个产品/商品，内容包括常见的文字描述、数量、单位价值、货币、原产国，以及已知时的协调关税/货物编号。在有需要时，申报的包裹价值通过包裹服务选项单独表示。MCP 不会自动推测关税编码、价值或原产国；缺失或无效的海关数据会由 UPS 返回提示修正。

推荐国际业务过程

1. 调用 rate_shipment 和 get_time_in_transit。

2. 调用 get_customs_requirements，然后调用 validate_custom_details。

3. 调用 estimate_landed_cost 并查看返回的关税、税费和警告。

4. 审查完整的运单载荷，并且在确实需要实际创建运单时，才调用 create_shipment，并设置 confirm=true。

5. 使用返回的追踪号 (如 track_package 或 track_shipment) 追踪。

6. 单独安排取货，使用 create_pickup 并设置 confirm=true。

UPS API 产品的批准、账户权限、production 审批、服务可用性和特定地区资格均由 UPS 控制。测试环境中的成功响应并不表示生产环境中的运单或取货已启用。