fleetsync-mcp

FleetSync MCP

A Model Context Protocol (MCP) server that exposes the FleetSync last-mile delivery platform to AI agents — enabling LLMs to query orders, manage routes, track drivers, and analyse delivery performance through natural language.

!MCP !TypeScript !Delivery !License

---

What It Does

Turns a logistics platform into a conversational interface. A dispatcher, operations manager, or automated agent can ask questions like:

• "What orders are scheduled for tomorrow?"
• "Show me all deliveries on route R-04"
• "Which routes today have stops more than 10km apart?"
• "Create a new delivery order for customer João, Rua das Flores 12, for Friday"

...and get structured, actionable answers — without opening the dashboard.

---

Architecture

flowchart LR
    A[AI Agent\nClaude / n8n / Custom] -->|MCP tool call| B[fleetsync-mcp\nMCP Server]
    B -->|REST API| C[FleetSync\nAPI v2]
    C -->|JSON response| B
    B -->|structured result| A

    subgraph Tools
        direction TB
        T1[Orders\nget · create · update · delete]
        T2[Routes\nget · create · update · delete]
        T3[Analytics\nanalyse route distances]
        T4[Drivers\nlist drivers]
    end

---

Tools (17 total)

Orders (8 tools)

| Tool | Description | |------|-------------| | fleetsync_get_order | Get order by number — status, client, address, driver, proof of delivery | | fleetsync_orders_by_date | Get all orders scheduled for a date | | fleetsync_orders_by_route | Get all orders assigned to a route code | | fleetsync_orders_status_changes | Get orders with status changes after a datetime (last 24h max) | | fleetsync_order_history | Get the last 25 history entries for an order | | fleetsync_create_order | Create a new unscheduled order | | fleetsync_update_order | Update an existing order's fields | | fleetsync_delete_order | Delete an order (irreversible) |

Routes (7 tools)

| Tool | Description | |------|-------------| | fleetsync_get_routes | List all routes | | fleetsync_routes_by_date | Get all routes for a date with driver and order count | | fleetsync_get_route | Get a specific route by code | | fleetsync_orders_by_route_date | Get orders grouped by route for a date | | fleetsync_create_route | Create a new route with optional driver, vehicle, and orders | | fleetsync_update_route | Update an existing route | | fleetsync_delete_route | Delete a route (irreversible) |

Analytics (1 tool)

| Tool | Description | |------|-------------| | fleetsync_analyze_route_distances | Compute haversine distances between consecutive stops. Flags pairs exceeding a configurable threshold (default: 5km). Returns total km, avg km, max km, and all violations |

Drivers & Auth (2 tools)

| Tool | Description | |------|-------------| | fleetsync_get_drivers | List all drivers with vehicle, phone, and active status | | fleetsync_test | Validate API credentials and check rate limits |

---

Stack

| Component | Tool | |-----------|------| | Protocol | Model Context Protocol SDK | | Language | TypeScript 5 + Node.js | | Schema validation | Zod | | Logistics platform | FleetSync API v2 |

---

Setup

Prerequisites

• Node.js 18+
• FleetSync account with API key

1. Install

git clone https://github.com/RobsonAdvincula/fleetsync-mcp.git
cd fleetsync-mcp
npm install
npm run build

2. Configure environment

FLEETSYNC_API_KEY=your_api_key
FLEETSYNC_BASE_URL=https://api.fleetsync.io/v2

3. Add to MCP host

Claude Desktop (claude_desktop_config.json): ``json { "mcpServers": { "fleetsync": { "command": "node", "args": ["/path/to/fleetsync-mcp/dist/index.js"], "env": { "FLEETSYNC_API_KEY": "your_api_key" } } } } ``

---

Example Interactions

Operations check: ``` User: "How many deliveries do we have tomorrow and which routes are active?"

→ fleetsync_orders_by_date({ date: "2026-03-26" }) ← { count: 47, orders: [...] } → fleetsync_routes_by_date({ date: "2026-03-26" }) ← { count: 4, routes: [{ code: "R-01", driver: "...", orders: 12 }, ...] }

Agent: "47 orders across 4 active routes tomorrow. Route R-03 has the most stops (18)." ```

Route quality check: ``` User: "Is route R-04 well optimised?"

→ fleetsync_analyze_route_distances({ code: "R-04", maxDistanceKm: 8 }) ← { total_km: 34.2, avg_km: 2.1, violations_count: 2, violations: [ { from: "ORD-112", to: "ORD-113", km: 11.4 }, { from: "ORD-118", to: "ORD-119", km: 9.7 } ] }

Agent: "Route R-04 has 2 problematic segments exceeding 8km. Consider reordering stops 112→113 and 118→119." ```

---

Route Distance Analysis

The fleetsync_analyze_route_distances tool uses the Haversine formula to compute great-circle distances between consecutive delivery stops using their GPS coordinates.

distance = 2R × arcsin(√(sin²(Δlat/2) + cos(lat₁)cos(lat₂)sin²(Δlon/2)))

Output includes per-segment distances, total route km, and a list of all threshold violations — useful for identifying poorly sequenced routes before dispatch.

---

License

MIT — free to use, adapt, and build on.

---

Built by Robson Advincula — AI & Automation Consultant