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

Clone and install:

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

Configure environment:

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

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:

License

MIT License - see LICENSE file

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
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

Shiplogic MCP Server

Integrations