UPS MCP Server

Servidor UPS MCP

Um servidor Model Context Protocol (MCP) para capacidades de envio e logística da UPS. Este servidor permite que sistemas de IA se integrem perfeitamente com as ferramentas da API da UPS.

Os usuários podem se integrar ao servidor MCP para permitir que agentes de IA facilitem eventos de rastreamento em seu nome, incluindo o rastreamento do status de uma remessa, a tela de trânsito mais recente e a data e hora de entrega esperadas. Os agentes serão autenticados usando credenciais de cliente OAuth fornecidas pelo usuário após a criação do aplicativo no Portal do Desenvolvedor da UPS.

Uso

Pré-requisitos

• Obter um Client ID e Client Secret: Crie um aplicativo no Portal do Desenvolvedor da UPS para obter suas credenciais OAuth – Client ID e Client Secret. (https://developer.ups.com/get-started?loc=en_US)
• Python 3.12 ou superior
• Instalar uv (Pacote Python)

Variáveis de Ambiente

• CLIENT_ID - Client ID da UPS
• CLIENT_SECRET - Client Secret da UPS
• ENVIRONMENT - Se deve apontar para Teste (CIE) ou Produção (valores aceitos: test, production)

Observação: Suas credenciais de API são sensíveis. Não as envie para o controle de versão. Recomendamos gerenciar segredos com segurança usando GitHub Secrets, um cofre ou um gerenciador de senhas.

Execução

Você pode executar o pacote usando uvx:

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

To use an older version, you can specify the version number like so:

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

Popular Integrations

Here are sample config files for popular integrations. Different MCP Clients may require modification.

Claude Desktop

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

GitHub Copilot no VS Code

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

Ferramentas Disponíveis

• track_package: Rastreie um pacote usando a API de Rastreamento da UPS

  Args:

  • inquiryNumber (str): o identificador exclusivo do pacote. Cada número de consulta deve ter entre 7 e 34 caracteres. Obrigatório.
  • locale (str): Código de idioma e país do usuário, separados por sublinhado. O valor padrão é 'en_US'. Não obrigatório.
  • returnSignature (bool): um booleano para indicar se uma assinatura é necessária, o padrão é false. Não obrigatório.
  • returnMilestones (bool): um booleano para indicar se informações detalhadas sobre os movimentos de um pacote são necessárias, o padrão é false. Não obrigatório.
  • returnPOD (bool): um booleano para indicar se uma prova de entrega é necessária, o padrão é false. Não obrigatório.

  Retorna:

  • str: A resposta da capacidade de rastreamento, esta é uma string de dados de rastreamento em json.

• validate_address: Valide um endereço usando a API de Validação de Endereço da UPS para os EUA ou Porto Rico

  Args:

  • addressLine1 (str): Os detalhes principais do endereço, incluindo o número da casa ou edifício e o nome da rua, ex. 123 Main St. Obrigatório.
  • addressLine2 (str): Informações adicionais como números de apartamento ou suíte, ex. Apt 4B. Não obrigatório.
  • politicalDivision1 (str): O código de estado ou província com duas letras, ex. GA para Geórgia. Obrigatório.
  • politicalDivision2 (str): O nome da cidade ou vila, ex. Springfield. Obrigatório.
  • zipPrimary (str): O código postal. Obrigatório.
  • zipExtended (str): Extensão do código postal de 4 dígitos. Somente para uso nos EUA. Não obrigatório.
  • urbanization (str): Divisão Política 3 de Porto Rico. Válido apenas para Porto Rico. Não obrigatório.
  • countryCode (str): O código do país, ex. US. Obrigatório.

  Retorna:

  • str: O corpo da resposta json da API de validação de endereço

O servidor UPS MCP ainda está em desenvolvimento ativo. Mais ferramentas em breve!