---
title: FleetMind MCP Server
emoji: 🚚
colorFrom: blue
colorTo: purple
sdk: docker
app_file: app.py
pinned: true
short_description: AI delivery dispatch MCP server with 29 management tools
tags:
  - mcp
  - building-mcp-track-enterprise
  - model-context-protocol
  - delivery-management
  - postgresql
  - fastmcp
  - gradio
  - enterprise
  - logistics
  - gemini
  - google-maps
  - ai-routing
---

<div align="center">

# 🚚 FleetMind MCP Server

### AI-Powered Delivery Dispatch for the Modern Enterprise

**The Problem:** Delivery dispatch is complex—coordinating drivers, optimizing routes, handling weather delays, and meeting SLAs requires constant human oversight.

**The Solution:** FleetMind exposes **29 AI-accessible tools** that let Claude (or any MCP client) manage your entire delivery operation through natural conversation.

**The Impact:** Dispatch managers can now say *"Assign this urgent fragile delivery to the best available driver considering weather and traffic"* and watch AI handle the complexity.

[![Demo Video](https://img.shields.io/badge/▶_Watch_Demo-FF0000?style=for-the-badge&logo=youtube&logoColor=white)](https://www.youtube.com/watch?v=IA9iD0VPvro)
[![Try It Live](https://img.shields.io/badge/🚀_Try_It_Live-7C3AED?style=for-the-badge)](https://mcp-1st-birthday-fleetmind-dispatch-ai.hf.space)
[![GitHub](https://img.shields.io/badge/GitHub-181717?style=for-the-badge&logo=github&logoColor=white)](https://github.com/mashrur-rahman-fahim/fleetmind-mcp)
[![LinkedIn Post](https://img.shields.io/badge/LinkedIn_Post-0A66C2?style=for-the-badge&logo=linkedin&logoColor=white)](https://www.linkedin.com/posts/kazi-wasif-amin-shammo-3a0307197_mcpbirthdayhackathon-ai-mcp-activity-7400938958521675776-Trax)
[![Facebook Post](https://img.shields.io/badge/Facebook_Post-1877F2?style=for-the-badge&logo=facebook&logoColor=white)](https://www.facebook.com/share/v/1BdfnLbuEY/)

</div>

---

## 📺 See It In Action

<div align="center">
  <a href="https://www.youtube.com/watch?v=IA9iD0VPvro">
    <img src="https://img.youtube.com/vi/IA9iD0VPvro/maxresdefault.jpg" alt="FleetMind Demo Video" width="560">
  </a>
  <p><b>▶️ Click to watch the demo video</b></p>
</div>

> Watch Gemini 2.0 Flash AI analyze weather, traffic, and driver capabilities to make intelligent assignment decisions with full reasoning transparency.

---

## ⚡ Quick Start (2 Minutes)

### Step 1: Get Your API Key
👉 **[Generate API Key](https://mcp-1st-birthday-fleetmind-dispatch-ai.hf.space/generate-key)** (copy immediately—shown once!)

### Step 2: Configure Claude Desktop
Add to your `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "fleetmind": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp-1st-birthday-fleetmind-dispatch-ai.hf.space/sse?api_key=YOUR_KEY_HERE"
      ]
    }
  }
}
```

### Step 3: Start Dispatching!
```
You: "Create an urgent delivery for Sarah at 456 Oak Ave, San Francisco,
     then use AI to find the best driver considering the current rain"

Claude: Uses geocode_address → create_order → intelligent_assign_order
        Returns: "Order ORD-... assigned to Mike (DRV-...).
        AI selected Mike because: closest driver with cold-storage van,
        safest route in current weather, 15 min ETA."
```

---

## 🏆 Why FleetMind?

| Feature | What It Does | Why It Matters |
|---------|--------------|----------------|
| **🤖 Gemini 2.0 Flash AI** | Analyzes 10+ parameters for intelligent driver assignment | Better decisions than rule-based systems |
| **🌦️ Weather-Aware Routing** | OpenWeatherMap integration for safety-first planning | Reduces weather-related delivery failures |
| **🔐 Multi-Tenant Auth** | Complete data isolation via deterministic user_id | Enterprise-ready security out of the box |
| **📊 SLA Tracking** | Automatic on-time/late/very-late classification | Built-in performance analytics |
| **🚦 Real-Time Traffic** | Google Routes API with live traffic data | Accurate ETAs, not guesstimates |
| **🏍️ Vehicle Optimization** | Motorcycle, bicycle, car, van, truck routing | Right routes for each vehicle type |

---

## 🛠️ The 29 Tools

<details>
<summary><b>📍 Geocoding & Routing (3 tools)</b></summary>

| Tool | Description |
|------|-------------|
| `geocode_address` | Convert address → GPS coordinates |
| `calculate_route` | Vehicle-specific routing with traffic, tolls, fuel estimates |
| `calculate_intelligent_route` | AI-powered routing with weather + traffic analysis |

</details>

<details>
<summary><b>📦 Order Management (8 tools)</b></summary>

| Tool | Description |
|------|-------------|
| `create_order` | Create delivery with mandatory deadline & SLA tracking |
| `count_orders` | Count by status/priority with breakdowns |
| `fetch_orders` | Paginated list with filters |
| `get_order_details` | Full order info including timing data |
| `search_orders` | Find by customer name/email/phone/ID |
| `get_incomplete_orders` | Active deliveries shortcut |
| `update_order` | Modify order with cascading updates |
| `delete_order` | Safe deletion with assignment checks |

</details>

<details>
<summary><b>👥 Driver Management (8 tools)</b></summary>

| Tool | Description |
|------|-------------|
| `create_driver` | Onboard with vehicle type, skills, capacity |
| `count_drivers` | Count by status/vehicle with breakdowns |
| `fetch_drivers` | Paginated list with filters |
| `get_driver_details` | Full info with reverse-geocoded location |
| `search_drivers` | Find by name/plate/phone/ID |
| `get_available_drivers` | Ready-for-dispatch shortcut |
| `update_driver` | Modify with location auto-timestamp |
| `delete_driver` | Safe deletion with assignment checks |

</details>

<details>
<summary><b>🔗 Assignment Management (8 tools) ⭐</b></summary>

| Tool | Description |
|------|-------------|
| `create_assignment` | Manual driver selection |
| **`auto_assign_order`** | **Nearest driver + capacity/skill validation** |
| **`intelligent_assign_order`** | **🤖 Gemini 2.0 Flash AI with full reasoning** |
| `get_assignment_details` | Query by assignment/order/driver ID |
| `update_assignment` | Status transitions with cascading |
| `unassign_order` | Revert to pending safely |
| `complete_delivery` | Mark done + auto-update driver location |
| `fail_delivery` | Track failure with GPS + structured reason |

</details>

<details>
<summary><b>🗑️ Bulk Operations (2 tools)</b></summary>

| Tool | Description |
|------|-------------|
| `delete_all_orders` | Mass delete with status filter & safety checks |
| `delete_all_drivers` | Mass delete with assignment safety blocks |

</details>

---

## 🏗️ Architecture

```
┌──────────────────────────────────────────────────────────────┐
│                      MCP Clients                              │
│     Claude Desktop  •  Continue  •  Cline  •  Custom Apps    │
└─────────────────────────────┬────────────────────────────────┘
                              │ SSE: /sse?api_key=fm_xxx
                              ▼
┌──────────────────────────────────────────────────────────────┐
│              Authentication Proxy (proxy.py)                  │
│  • Captures API key from SSE connection                       │
│  • Links session_id → api_key for tool calls                  │
│  • Keep-alive pings every 30s                                 │
└─────────────────────────────┬────────────────────────────────┘
                              ▼
┌──────────────────────────────────────────────────────────────┐
│              FastMCP Server (server.py)                       │
│  • ApiKeyAuthMiddleware validates every call                  │
│  • 29 tools with user_id filtering                            │
│  • 2 real-time resources (orders://all, drivers://all)        │
└──────────┬──────────┬────────────┬──────────┬────────────────┘
           ▼          ▼            ▼          ▼
    ┌──────────┐ ┌─────────┐ ┌──────────┐ ┌───────────┐
    │PostgreSQL│ │ Google  │ │  Gemini  │ │OpenWeather│
    │  (Neon)  │ │Maps API │ │2.0 Flash │ │  Map API  │
    │ user_id  │ │Geocoding│ │Intelligent││  Weather  │
    │isolation │ │ Routing │ │Assignment│ │   Data    │
    └──────────┘ └─────────┘ └──────────┘ └───────────┘
```

---

## 🔐 Authentication & Security

FleetMind uses a **3-layer authentication system** for enterprise-grade security:

| Layer | Component | Function |
|-------|-----------|----------|
| 1 | **Proxy** | Captures API key from URL, links sessions |
| 2 | **Middleware** | Validates every tool call, injects user context |
| 3 | **Database** | All queries filter by `user_id` (complete isolation) |

**Security Features:**
- ✅ SHA-256 hashed key storage (never plaintext)
- ✅ One-time key display (can't retrieve later)
- ✅ Deterministic user_id from email (key rotation preserves data)
- ✅ Production safeguards (SKIP_AUTH blocked when ENV=production)

<details>
<summary><b>View Complete Auth Flow</b></summary>

```
1. Generate API Key → user_id = user_{MD5(email)[:12]}
2. Configure Claude → URL includes ?api_key=fm_xxx
3. SSE Connection → Proxy captures and stores key
4. Tool Call → Proxy injects key, middleware validates
5. Database Query → WHERE user_id = 'user_xxx'
6. Result → Only user's own data returned
```

</details>

---

## 🚀 Deployment

### Production (HuggingFace Space)
Already deployed at: **https://mcp-1st-birthday-fleetmind-dispatch-ai.hf.space**

### Local Development
```bash
git clone <repository-url>
cd fleetmind-mcp
pip install -r requirements.txt

# Configure .env with your API keys
python start_with_proxy.py  # Runs proxy (7860) + FastMCP (7861)
```

---

## 📊 Technical Specifications

| Metric | Value |
|--------|-------|
| **Tools** | 29 |
| **Resources** | 2 (orders://all, drivers://all) |
| **Database** | PostgreSQL (Neon serverless) |
| **AI Model** | Gemini 2.0 Flash (gemini-2.0-flash-exp) |
| **Transport** | SSE (Server-Sent Events) |
| **Framework** | FastMCP 2.13.0 |
| **Language** | Python 3.10+ |

---

## 🔗 Links

| Resource | URL |
|----------|-----|
| **Live Demo** | https://mcp-1st-birthday-fleetmind-dispatch-ai.hf.space |
| **MCP Endpoint** | https://mcp-1st-birthday-fleetmind-dispatch-ai.hf.space/sse |
| **Generate API Key** | https://mcp-1st-birthday-fleetmind-dispatch-ai.hf.space/generate-key |
| **HuggingFace Space** | https://huggingface.co/spaces/MCP-1st-Birthday/fleetmind-dispatch-ai |

---

## 👥 Team

**FleetMind Development Team**

*MCP 1st Birthday Hackathon - Track 1: Building MCP Servers (Enterprise Category)*

---

## 📄 License

MIT License - see [LICENSE](LICENSE) for details.

---

<div align="center">

**Built with ❤️ using [FastMCP](https://gofastmcp.com) for the MCP 1st Birthday Hackathon**

[![MCP](https://img.shields.io/badge/MCP-1.0-orange)](https://modelcontextprotocol.io)
[![FastMCP](https://img.shields.io/badge/FastMCP-2.13.0-blue)](https://gofastmcp.com)
[![Python](https://img.shields.io/badge/Python-3.10+-brightgreen)](https://python.org)

</div>