FleetMind

FleetMind MCP Server provides 29 AI-enabled tools to manage an enterprise delivery operation through natural conversation. You can assign orders, optimize routes, consider weather and traffic, and track SLA performance, all without writing code for every decision. This server connects your MCP client to geocoding, routing, order and driver management, and intelligent assignment capabilities to streamline dispatch at scale.

How to use

Interact with FleetMind using your MCP client to issue natural-language requests. Start by obtaining an API key and configuring your MCP client to connect to the FleetMind server. Once connected, you can create orders, query drivers and orders, and trigger intelligent assignments. For example you can say, “Create an urgent delivery for Sarah at 456 Oak Ave, San Francisco, and have AI select the best driver considering the current weather.” The system will geocode the address, create the order, and assign it to the most suitable driver based on live data such as weather, traffic, and vehicle suitability.

The server exposes 29 distinct tools across geocoding, routing, order management, driver management, assignment management, and bulk operations. You can drive real-time decisions like auto_assign_order or intelligent_assign_order to ensure optimal driver selection and SLA adherence. All actions are filtered by your user_id to maintain data isolation in multi-tenant deployments.

How to install

Prerequisites: Python 3.10+ and a compatible environment for running the server. You should also have an API key provisioning flow for FleetMind.

1. Clone the project repository (adjust to your workflow):

git clone <repository-url>
cd fleetmind-mcp```

2. Install Python dependencies:

pip install -r requirements.txt

3. Prepare environment variables. Create a local .env file or export variables in your shell. At minimum, provide your API key and set production mode as needed. For example:

export FM_API_KEY=YOUR_API_KEY```

4) Start the server using the local development flow described in the guide:
```python start_with_proxy.py # Runs proxy (7860) + FastMCP (7861)```

## Configuration and security notes

FleetMind uses a three-layer authentication scheme to protect data: a proxy captures the API key from the connection, middleware validates each tool call and injects user context, and all database queries filter by user\_id to enforce complete data isolation. Production deployments encourage using environment-based safeguards, including a production flag to disable certain development features.

Key security considerations:
- API keys are never stored in plaintext; keys are hashed or rotated as configured.
- Use deterministic user\_id derivation (based on user identifiers like email) to maintain data isolation when keys rotate.
- Ensure production mode blocks skip-auth pathways and enforces strict access controls.

## Architecture overview

The FleetMind MCP Server architecture connects MCP clients (for example Claude Desktop) through an authentication proxy to the FastMCP server, which hosts 29 tools. Real-time resources exposed are orders and drivers. Data connections include PostgreSQL for data storage, Google Maps for routing and geocoding, Gemini 2.0 Flash AI for intelligent assignment, and weather data from a weather API. This setup enables end-to-end delivery optimization with data isolation per user.

## Usage examples and capabilities

You can perform actions such as:
- geocode\_address to convert addresses to GPS coordinates
- calculate\_route for vehicle-specific routing with traffic and costs
- create\_order to schedule deliveries with SLA tracking
- create\_assignment to manually assign drivers
- intelligent\_assign\_order to let AI choose the best driver with full reasoning
- complete\_delivery to mark a delivery finished and update driver location
- delete\_all\_orders to mass-delete orders with safeguards
All tool calls respect the user\_id context to ensure enterprise-grade isolation.

## Notes on deployment and live endpoints

Production deployments can run on hosted spaces or private infrastructure. The server exposes an MCP URL via SSE that your MCP client can listen to for responses. To connect a client, configure the MCP endpoint in your client with the appropriate API key and use the provided AWS-like or Cloud-hosted URLs as your remote endpoint.

## Available tools

### geocode\_address

Convert a physical address into GPS coordinates to enable accurate mapping and routing.

### calculate\_route

Compute a vehicle-specific route with current traffic, tolls, and fuel estimates.

### calculate\_intelligent\_route

AI-powered routing that analyzes weather and traffic to optimize every leg.

### create\_order

Create a delivery with a mandatory deadline and SLA tracking to ensure timely fulfillment.

### count\_orders

Count orders by status or priority and provide breakdowns for management oversight.

### fetch\_orders

Retrieve a paginated list of orders with filters for status, customer, or date.

### get\_order\_details

Get complete information for a single order, including timing and SLA data.

### search\_orders

Find orders by customer name, email, phone, or order ID.

### get\_incomplete\_orders

Quick access to active deliveries that require attention.

### update\_order

Modify order details with cascading updates to related entities.

### delete\_order

Safe deletion with checks to ensure no active assignments.

### create\_driver

Onboard drivers with vehicle type, skills, and capacity information.

### count\_drivers

Count drivers by status and vehicle type with breakdowns.

### fetch\_drivers

Paginated list of drivers with filters for location and status.

### get\_driver\_details

Full driver info including reverse-geocoded location data.

### search\_drivers

Find drivers by name, plate, phone, or ID.

### get\_available\_drivers

Shortcut to list drivers ready for dispatch.

### update\_driver

Update driver details with location auto-timestamping.

### delete\_driver

Safe deletion with checks to prevent orphaned assignments.

### create\_assignment

Manually assign a driver to an order.

### auto\_assign\_order

Automatically assign the nearest suitable driver with capacity/skill validation.

### intelligent\_assign\_order

AI-powered assignment with full reasoning from Gemini 2.0 Flash.

### get\_assignment\_details

Query details by assignment, order, or driver ID.

### update\_assignment

Manage status transitions with cascading updates.

### unassign\_order

Revert an assignment back to pending safely.

### complete\_delivery

Mark a delivery as complete and update driver location accordingly.

### fail\_delivery

Record a delivery failure with GPS context and a structured reason.

### delete\_all\_orders

Mass delete orders with filters and safety checks.

### delete\_all\_drivers

Mass delete drivers with assignment safety blocks.