---

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.

</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 (copy immediately—shown once!)

Step 2: Configure Claude Desktop

Add to your claude_desktop_config.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

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 for details.

---

<div align="center">

Built with ❤️ using FastMCP for the MCP 1st Birthday Hackathon

</div>