Shiplogic MCP Server

A Model Context Protocol (MCP) server that provides seamless integration with the Shiplogic shipping API. Built with the MCP SDK and TypeScript for type safety and better developer experience.

Demo

# Example conversation with Claude:
User: "Get shipping rates from Cape Town to Johannesburg for a 2.5kg parcel"
Claude: "I'll check shipping rates for you..."

[Using tool: get_shipping_rates]
Result: Economy service - R95 (2-3 days delivery)

User: "Book the economy service"
Claude: "Creating shipment..."

[Using tool: create_shipment]
Result: Shipment created! Tracking: QR4FVL

Features

• 🚚 Get shipping rates - Calculate shipping costs between addresses
• 📦 Create shipments - Book shipments with automatic tracking
• 🔍 Track packages - Real-time shipment tracking
• ❌ Cancel shipments - Cancel bookings when needed
• ➕ Optional services - Access add-on rates for special services
• 📚 Address book management - Store and manage frequently used addresses

Installation

Prerequisites

• Node.js 18+
• npm or yarn
• Shiplogic API key (get one at shiplogic.com)

Quick Start

1. Clone and install:

git clone https://github.com/jlwainwright/shiplogic-mcp.git
cd shiplogic-mcp
npm install

2. Configure environment:

cp .env.example .env
# Edit .env and add your Shiplogic API key

3. Build the server:

npm run build

Usage

With Claude Desktop

Add this to your Claude Desktop configuration:

{
  "mcpServers": {
    "shiplogic": {
      "command": "node",
      "args": ["/absolute/path/to/shiplogic-mcp/dist/index.js"],
      "env": {
        "SHIPLOGIC_API_KEY": "your_api_key_here"
      }
    }
  }
}

With MCP Inspector

Test the server using the MCP Inspector:

npm run inspect

Standalone

Run the server directly:

npm run dev

Available Tools

get_shipping_rates

Calculate shipping rates between two addresses.

{
  collection_address: {
    street_address: string,
    city: string,
    code: string,
    country?: string,
    type?: "residential" | "business"
  },
  delivery_address: {
    street_address: string,
    city: string,
    code: string,
    country?: string,
    type?: "residential" | "business"
  },
  parcels: [{
    length: number,    // cm
    width: number,     // cm
    height: number,    // cm
    weight: number,    // kg
    description?: string
  }],
  declared_value?: number
}

create_shipment

Create a new shipment with tracking.

{
  service_level_code: string,  // e.g., "ECO"
  collection_address: { /* same as above */ },
  delivery_address: { /* same as above */ },
  parcels: [{ /* same as above */ }],
  collection_contact: {
    name: string,
    mobile_number?: string,
    email?: string
  },
  delivery_contact: {
    name: string,
    mobile_number?: string,
    email?: string
  },
  customer_reference?: string,
  mute_notifications?: boolean
}

track_shipment

Track a shipment by reference number.

{
  tracking_number: string
}

cancel_shipment

Cancel an existing shipment.

{
  tracking_reference: string
}

get_opt_in_rates

Get optional add-on service rates.

{
  collection_address: { /* address object */ },
  delivery_address: { /* address object */ }
}

add_address_to_book

Add an address to the account's address book.

{
  account_id: number,
  address: {
    street_address: string,
    city: string,
    code: string,
    country?: string,
    type?: "residential" | "business",
    company?: string
  },
  name?: string,            // Name for this address entry
  type?: "collection" | "delivery"  // Address type
}

get_address_book

Retrieve addresses from the account's address book.

{
  account_id: number,
  type?: "collection" | "delivery"  // Optional filter by type
}

remove_address_from_book

Remove an address from the account's address book.

{
  account_id: number,
  address_id: number
}

Configuration

Environment variables:

Variable	Description	Required	Default
SHIPLOGIC_API_KEY	Your Shiplogic API key	Yes	-
SHIPLOGIC_API_URL	API base URL	No	https://api.shiplogic.com

Development

Project Structure

shiplogic-mcp-official/
├── src/
│   └── index.ts        # Main server implementation
├── dist/               # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
├── .env.example
└── README.md

Scripts

• npm run build - Compile TypeScript
• npm run dev - Build and run
• npm run inspect - Run with MCP Inspector

Testing

# Run with MCP Inspector
npm run inspect

# In another terminal, test the tools
curl -X POST http://localhost:3000/tools/list

API Reference

This server integrates with Shiplogic API v2. For detailed API documentation, see:

• Shiplogic API Docs
• MCP Protocol Specification

License

MIT License - see LICENSE file

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Support

• 🐛 Issues: GitHub Issues
• 📧 Email: your.email@example.com
• 📚 Docs: Wiki
• ☕ Support My Work: Buy Me a Coffee

If you find this project helpful, consider supporting my work. Your support helps me dedicate more time to open source development and create better tools for the community.

Acknowledgments

• Built with Model Context Protocol SDK
• Powered by Shiplogic API

---

Made with ❤️ by Jacques Wainwright