ShipBoss

Servidor MCP ShipBoss

Um servidor MCP que fornece capacidades de envio e logística por meio de conversas com IA. Conecte-se à FedEx, UPS e DHL para obter tarifas, criar etiquetas, rastrear pacotes e gerenciar remessas de carga.

🔑 Importante: Você precisará de um token de API ShipBoss para usar este servidor. Obtenha um em ShipBoss Admin → API Integrations.

📁 Esta configuração usa o modo de desenvolvimento local com caminhos de ambiente virtual para máxima compatibilidade e controle.

🚀 Configuração Rápida (5 Minutos)

Pré-requisitos

• Python 3.9+ instalado
• Conta ShipBoss com token de API (obtenha um na seção de administração em ship.shipboss.io)

Instalação Passo a Passo

Passo 1: Obtenha seu Token de API ShipBoss 🔑 Isso é necessário para que o servidor se comunique com as APIs ShipBoss.

1. Acesse ShipBoss e faça login
2. Navegue até sua seção Admin → API Integrations
3. Gere um novo token de API e copie-o
4. Mantenha este token seguro - você precisará dele no próximo passo

Passo 2: Crie um Ambiente Virtual 🐍 Usar um ambiente virtual é obrigatório para evitar conflitos de dependências com a instalação Python do seu sistema.

# Create a virtual environment
python -m venv shipboss_env

# Activate it
# Windows:
shipboss_env\Scripts\activate
# macOS/Linux:
source shipboss_env/bin/activate

# Install the package
pip install shipboss-mcp-server

⚠️ Importante: Usar um ambiente virtual é obrigatório para evitar conflitos de dependências com a instalação Python do seu sistema.

Passo 3: Configure o Token de API 🔑 O servidor precisa do seu token de API para autenticar com a ShipBoss. Escolha um destes métodos:

Opção A: Arquivo .env (Mais Simples - Automático) 📁

# Create environment file in the project directory
echo "SHIPBOSS_API_TOKEN=your_api_token_here" > .env

# Or use the provided template
cp example.env .env  # Then edit .env with your actual token

Em seguida, use esta configuração no seu cliente MCP:

{
  "mcpServers": {
    "shipboss-mcp": {
      "command": "C:\\path\\to\\shipboss_env\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\shipboss-mcp\\shipboss_mcp_server.py"]
    }
  }
}

Opção B: Argumentos de Linha de Comando

Adicione seu token diretamente na configuração MCP:

{
  "mcpServers": {
    "shipboss-mcp": {
      "command": "C:\\path\\to\\shipboss_env\\Scripts\\python.exe",
      "args": [
        "C:\\path\\to\\shipboss-mcp\\shipboss_mcp_server.py",
        "--api-token", "your_api_token_here"
      ]
    }
  }
}

Opção C: Variável de Ambiente

{
  "mcpServers": {
    "shipboss-mcp": {
      "command": "C:\\path\\to\\shipboss_env\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\shipboss-mcp\\shipboss_mcp_server.py"],
      "env": {
        "SHIPBOSS_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Nota: Substitua C:\path\to\shipboss_env pelo caminho real do seu ambiente virtual e C:\path\to\shipboss-mcp pelo caminho real do diretório do seu projeto.

Como Encontrar Seus Caminhos

Para Windows:

# Find your virtual environment Python executable
cd shipboss_env\Scripts
echo %CD%\python.exe

# Find your project directory
cd ..\..
echo %CD%\shipboss_mcp_server.py

Para macOS/Linux:

# Find your virtual environment Python executable
which python  # Should show the venv python path

# Find your project directory
pwd  # Current directory containing shipboss_mcp_server.py

Verificação rápida:

# Test that your paths work
"C:\path\to\shipboss_env\Scripts\python.exe" "C:\path\to\shipboss-mcp\shipboss_mcp_server.py" --api-token your_token_here

Passo 4: Teste Sua Configuração 🧪 Certifique-se de que seu ambiente virtual esteja ativado, reinicie seu cliente MCP e tente estes comandos:

• "Obtenha tarifas de envio de Nova York para Los Angeles para um pacote de 2lb"
• "Crie uma etiqueta FedEx Ground de 123 Main St, Nova York, NY para 456 Oak Ave, Los Angeles, CA"

Ferramentas Disponíveis

• ping - Verificação de saúde
• get_parcel_rates - Obter tarifas de envio de pacotes
• create_parcel_label - Criar etiquetas de envio de pacotes com URLs de download direto
• track_parcel - Rastrear remessas de pacotes
• create_pickup - Agendar coletas de transportadoras
• cancel_pickup - Cancelar coletas agendadas
• get_freight_rates - Obter cotações de frete
• track_freight - Rastrear remessas de frete

Solução de Problemas

Problemas Comuns:

1. "comando python não encontrado" ou "python.exe não encontrado" ❌: Certifique-se de que seu ambiente virtual esteja ativado antes de executar o servidor.

   • Solução: Ative seu ambiente virtual primeiro:

     # Windows: shipboss_env\Scripts\activate
     # macOS/Linux: source shipboss_env/bin/activate
     

2. Erro "token de API obrigatório" 🔐: Certifique-se de ter seu token de API configurado usando um destes métodos:

   • Mais fácil: Crie um arquivo .env com SHIPBOSS_API_TOKEN=your_token (carregado automaticamente)
   • Adicione --api-token your_token aos argumentos na sua configuração MCP
   • Defina SHIPBOSS_API_TOKEN na seção de ambiente da sua configuração MCP
   • Verifique seu token: Certifique-se de que seja de ShipBoss API Integrations

3. "Arquivo .env não encontrado": O arquivo .env deve estar no diretório do projeto onde shipboss_mcp_server.py está localizado (ou adicione a chave de API à configuração JSON conforme detalhado acima).

   • Verifique se o arquivo existe: ls -la .env
   • Verifique o formato do token: cat .env (deve mostrar SHIPBOSS_API_TOKEN=your_token_here)

4. Comando não encontrado: Certifique-se de que o pacote esteja instalado e o comando shipboss-mcp-server esteja disponível no seu PATH.

5. Problemas de caminho na configuração MCP: Certifique-se de que seus caminhos na configuração MCP estejam corretos:

   • Use o caminho completo para o executável Python do seu ambiente virtual
   • Use o caminho completo para o seu arquivo shipboss_mcp_server.py
   • Certifique-se de que os caminhos usem os separadores corretos (\ para Windows, / para macOS/Linux)