UPS MCP-Server

Ein Model Context Protocol-Server für UPS-Versand- und Logistik-APIs. Ermöglicht KI-Agenten das Erstellen von Sendungen, die Paketverfolgung, das Abrufen von Versandkosten, die Adressvalidierung, die Planung von Abholungen und das Finden von UPS-Standorten.

Schnellinstallation

Fügen Sie dies zu Ihrer MCP-Konfiguration hinzu (~/.cursor/mcp.json, .cursor/mcp.json oder 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"
      }
    }
  }
}

Erhalten Sie Ihre Zugangsdaten im UPS Developer Portal.

Tools

Voraussetzungen

• Node.js 20+

• Zugangsdaten für das UPS Developer Portal (Erste Schritte)

• UPS-Kundennummer (für Versand und Preisberechnung)

Installation

npx ups-mcp

Oder global installieren:

npm install -g ups-mcp

Konfiguration

Umgebungsvariablen

Anwendungsbeispiele

Sendung erstellen

"Versende ein 5lb Paket von 123 Main St, Atlanta GA 30301 an 456 Oak Ave, Los Angeles CA 90001 via UPS Ground"

Versandkosten abrufen

"Wie hoch sind die Versandkosten für ein 10lb Paket von NYC nach Chicago?"

Paket verfolgen

"Verfolge Paket 1Z999AA10123456784"

Adresse validieren

"Ist 1600 Pennsylvania Ave NW, Washington DC 20500 eine gültige Adresse?"

Abholung planen

"Plane eine Abholung für morgen um 9 Uhr für 3 Pakete in unserem Lager"

Entwicklung

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

Testen mit dem MCP Inspector

npm run inspector

Lokal ausführen

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

Architektur

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

Sicherheit

Ihre API-Zugangsdaten sind vertraulich. Übertragen Sie diese niemals in die Versionsverwaltung. Verwenden Sie Umgebungsvariablen oder einen Secrets-Manager.

Haftungsausschluss

Dieses Projekt ist ein unabhängiges, inoffizielles Tool eines Drittanbieters. Es ist nicht mit United Parcel Service, Inc. (UPS) oder seinen Tochtergesellschaften verbunden, wird von diesen nicht unterstützt, gesponsert oder in irgendeiner Weise offiziell mit ihnen in Verbindung gebracht.

"UPS" und die UPS-Marke sind eingetragene Marken von United Parcel Service of America, Inc. Alle anderen Marken sind Eigentum ihrer jeweiligen Inhaber. Die Verwendung dieser Namen dient nur zu Identifikations- und Interoperabilitätszwecken und impliziert keine Billigung.

Diese Software wird "WIE BESEHEN" ohne jegliche Gewährleistung bereitgestellt. Sie sind allein verantwortlich für:

• Die Einhaltung der UPS Technology Agreement und aller geltenden UPS-Nutzungsbedingungen, Ratenbegrenzungen und Richtlinien zur akzeptablen Nutzung.

• Die Sicherung Ihrer API-Zugangsdaten und Ihres UPS-Kontos.

• Alle Aktivitäten, die über dieses Tool mit Ihrem UPS-Konto durchgeführt werden.

• Die Einhaltung aller geltenden Gesetze und Vorschriften in Ihrer Gerichtsbarkeit.

Die Autoren und Mitwirkenden übernehmen keine Haftung für Schäden, die aus der Nutzung dieser Software oder der darüber aufgerufenen UPS-APIs entstehen.

Mitwirken

Beiträge sind willkommen! Bitte lesen Sie CONTRIBUTING.md für Richtlinien.

Lizenz

MIT