metadata
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
🚚 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.
📺 See It In Action
▶️ Click to watch the demo video
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
📍 Geocoding & Routing (3 tools)
| 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 |
📦 Order Management (8 tools)
| 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 |
👥 Driver Management (8 tools)
| 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 |
🔗 Assignment Management (8 tools) ⭐
| 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 |
🗑️ Bulk Operations (2 tools)
| Tool | Description |
|---|---|
delete_all_orders |
Mass delete with status filter & safety checks |
delete_all_drivers |
Mass delete with assignment safety blocks |
🏗️ 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)
View Complete Auth Flow
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
🚀 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.
Built with ❤️ using FastMCP for the MCP 1st Birthday Hackathon
