UPS MCP Server

Un servidor del Model Context Protocol (MCP) para capacidades de envío y logística de UPS. Este servidor permite que los sistemas de IA se integren sin problemas con las herramientas de la API de UPS.

Los usuarios pueden utilizar el servidor MCP para que los agentes de IA faciliten el seguimiento de eventos en su nombre, incluido el estado de un envío, la pantalla de tránsito más reciente y la fecha y hora de entrega esperadas. Los agentes se autenticarán mediante credenciales de cliente OAuth proporcionadas por el usuario después de crear una aplicación en el portal de desarrolladores de UPS.

Uso

Prerrequisitos

• Obtenga un Client ID y un Client Secret: cree una aplicación en UPS Developer Portal para obtener sus credenciales OAuth: Client ID y Client Secret. (https://developer.ups.com/get-started?loc=en_US)

• Python 3.12 o superior

• Instale uv (paquete de Python)

Variables de entorno

• CLIENT_ID — Client ID de UPS

• CLIENT_SECRET — Client Secret de UPS

• ENVIRONMENT — Si se debe apuntar al entorno Test (CIE) o Production (valores aceptados: test, production)

Nota: Sus credenciales de API son información sensible. No las incluya en el control de versiones. Recomendamos gestionar los secretos de forma segura con GitHub Secrets, un almacén de secretos o un gestor de contraseñas.

Ejecución

Puede ejecutar el paquete usando uvx:

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

Para usar una versión anterior, puede especificar el número de versión de esta forma:

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

Related MCP server: UPS MCP Server

Integraciones populares

Estos son ejemplos de archivos de configuración para integraciones populares. Es posible que distintos clientes MCP requieran modificaciones.

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

Herramientas disponibles

El servidor ahora admite el flujo principal de envíos internacionales:

• validate_address — valida direcciones de calle de EE. UU. y Puerto Rico. La API de validación de direcciones de UPS no es un validador internacional de direcciones general; los datos internacionales de destino se suministran en el payload de gestión de envíos y tarifas.

• rate_shipment — compara los servicios y cargos de UPS. Es una estimación y no compra el envío.

• get_time_in_transit — estima el tiempo de tránsito para una solicitud que incluye origen, destino y paquete.

• get_customs_requirements — obiene los campos aduaneos que requiere UP.

• validate_customs_details — valida los datos destacada.

• estimate_landed_cost — estima los aranceles, impuestos y otros costes devueltos por UPS.

• create_shipment — crea un envío y de devuelve los datos de enví, seguimiento y etiqueta de UPS. Esto requiere confirm=true y puede generar cargos.

• recover_label — recupera una etiqueta mediante el contrato de la API de envíos.

• void_shipment — anula un envío y requiere confirm=true.

• rate_pickup — obiene una estimación de recogida sin programar ninguna.

• create_pickup — programá una recogida y requiere confirm=true.

• get_pickup_status — comprubea el estado de recogida pendiente para una cuenta.

• cancel_pickup — cancela una recogida y requiere confirm=true.

• find_pickup_service_centers — busca centros de servicio de recogida.

• get_pickup_political_divisions — aits geographic political divisions válidas para recogidas de un país.

• customs_description_guidance — inicia, contina o enví comentarios por una sesión interactiva de orientación de decripción del producto y de mercancías/HTS de Export Assure with action=start|continue|feedback.

• submit_export_assure — envío de los datos de un envío transfronterizo para obtener orientación sobre normativas.

• upload_paperless_document, push_paperedless_document_to_image_repository y delete_paperless_document — gestion de documentos aduaneos y de enví, "paperless" de UPS. La eliminación requires confirm=true.

• lookup_dangerous_goods_chemical_reference — busca datos de sustancias químicas.

• dangerous_goods_acceptance_precheck — ejecuta la preverificación de aceptación de mercancías nfragrosas de UPS.

• get_delivery_intercept_options — to obiene his elegibilid for integración after el envío or for cargos with action=eligibility|charges.

• apply_delivery_intercept — cambia la gestación de entrega de un paqueete en tránsito with action=redirecacc|cWillcal|retorno|reeschedule; requiere confirm=true.

• cancel_delivery_intercept — cancela una solicitud de interceptación previa; requiere confirm=true.

• manage_tracking_aler_subscription — admindára las admonitors permanentes de Track Alert with scope=package|account y action=subscribe|unsubscribe; requiere confirm=true.

• find_ups_locations — embeups Stores, ubicaciones de locations and elsewhere.

• create_guaranteed_landed_cost_quote — solicita una cotización del coste final garantizado when la cuenta de UPS tiene acceso.

• track_package, track_by_reference y track_shipment — rees state de one paquete, los paquetos que couenzan con la referecia, en un envío.

The cuerpos de solicitudes complejos de UPS se aceptan como objsons JSON validados que se ajustan a los wrappers de solicitud en ../api-ocumentation. Esto preserve el soporte para los campos de de aduanas internationalgon, service, empaque and account that Varies segun el productos de UPS, mientras mantiene estables los nombres de operaciones comunes del MCP.

Para la facturación de envíos, pase accountNumber a create_Package or provide the fieldinistrative equivalente de UPS in the wrapper de la solicitud. El argumen de conveniencia se escribe en:

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

In declaración internacional de aduaneas se unsítvia in los campos de builtin the wrapper de enví the "international form" of UPS (and also validate with validate_customs_details). Una declaración típica tiene or more goods with a decripción en lenguaje de c entendedor, cantidad, valor of unidad, moneda, país de origem and código of arancel/mercancías when are known. The "de package" is represented separately by the "de package" services, if necesari. MCP does not deducir códigos de arancel, valor or p país de origen. Missing or invalid valid aduaneos is devuelto by UPS for corrección.

Flujo internaional recomendado

1. Use rate_shipment and get_time_in_transit.

2. Let's continue with get_customs_requirements and then validate_customs_details.

3. Call estimate_landed_cost and review the returned duties, taxes and warnings.

4. Reide the "completo" shipment and create_shipment with confirm=true only when the shipment must actually be created.

5. Track the returned tracking number with track_package or track_shipment.

6. Schedule the pickup separately with the create_pickup and confirm=true.

The product approval of the UPS application, account permissions, production approval, and specific country and service are controlled by the UPS. A successful test in the help environment does not necessarily mean that the production has been planned.