Servidor MCP de UPS

Un servidor del Protocolo de Contexto de Modelo (MCP) para las APIs de envío y logística de UPS. Permite a los agentes de IA crear envíos, rastrear paquetes, obtener tarifas, validar direcciones, programar recolecciones y encontrar ubicaciones de UPS.

Instalación rápida

Añádelo a tu configuración de MCP (~/.cursor/mcp.json, .cursor/mcp.json o 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"
      }
    }
  }
}

Obtén tus credenciales en el Portal de Desarrolladores de UPS.

Herramientas

Requisitos previos

• Node.js 20+

• Credenciales del Portal de Desarrolladores de UPS (Comenzar)

• Número de cuenta de UPS (para envíos y tarifas)

Instalación

npx ups-mcp

O instálalo globalmente:

npm install -g ups-mcp

Configuración

Variables de entorno

Ejemplos de uso

Crear un envío

"Envía un paquete de 5 libras desde 123 Main St, Atlanta GA 30301 a 456 Oak Ave, Los Angeles CA 90001 vía UPS Ground"

Obtener tarifas

"¿Cuáles son las tarifas de envío para un paquete de 10 libras de NYC a Chicago?"

Rastrear un paquete

"Rastrea el paquete 1Z999AA10123456784"

Validar una dirección

"¿Es 1600 Pennsylvania Ave NW, Washington DC 20500 una dirección válida?"

Programar una recolección

"Programa una recolección mañana a las 9am para 3 paquetes en nuestro almacén"

Desarrollo

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

Pruebas con el Inspector MCP

npm run inspector

Ejecución local

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

Arquitectura

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

Seguridad

Tus credenciales de API son confidenciales. Nunca las subas al control de versiones. Utiliza variables de entorno o un gestor de secretos.

Descargo de responsabilidad

Este proyecto es una herramienta independiente, no oficial y de terceros. No está afiliado, respaldado, patrocinado ni conectado oficialmente de ninguna manera con United Parcel Service, Inc. (UPS) o cualquiera de sus subsidiarias.

"UPS" y la marca UPS son marcas registradas de United Parcel Service of America, Inc. Todas las demás marcas comerciales son propiedad de sus respectivos dueños. El uso de estos nombres es solo para fines de identificación e interoperabilidad y no implica respaldo.

Este software se proporciona "TAL CUAL", sin garantía de ningún tipo. Usted es el único responsable de:

• Cumplir con el Acuerdo de Tecnología de UPS y todos los términos de servicio, límites de tarifas y políticas de uso aceptable de UPS aplicables.

• Proteger sus credenciales de API y su cuenta de UPS.

• Toda la actividad realizada a través de su cuenta de UPS mediante esta herramienta.

• El cumplimiento de todas las leyes y regulaciones aplicables en su jurisdicción.

Los autores y colaboradores no aceptan responsabilidad por daños derivados del uso de este software o de las APIs de UPS a las que se accede a través de él.

Contribución

¡Las contribuciones son bienvenidas! Por favor, consulta CONTRIBUTING.md para conocer las pautas.

Licencia

MIT