fleet-mcp-server
# fleet-mcp-server
An [MCP](https://modelcontextprotocol.io) server that lets an AI assistant answer fleet
telematics questions in plain language: which vehicles idle the most and what it costs,
which engine faults need attention first, and which drivers need coaching.
Ask Claude *"Which three vehicles wasted the most fuel idling last week, and what did it
cost us?"* and it calls `idling_report`, gets structured data back, and answers with numbers.
> All data is **simulated**. This is a personal project showing how I would put a
> natural-language layer over telematics data for a customer. It contains no employer or
> customer data.
## Why I built it
In solutions engineering, the same fleet questions come up in almost every customer
conversation, and the answer usually means someone building a report. MCP turns those
questions into tool calls an assistant can make on its own. This repo is the smallest
complete version of that pattern: a data layer, a tool layer, tests, and a client.
## Tools
| Tool | What it answers |
| --- | --- |
| `list_vehicles` | What is in the fleet, optionally by depot |
| `vehicle_summary` | Trips, distance, idle time, fuel economy and active faults for one vehicle |
| `idling_report` | Idle-time ranking with the estimated fuel cost of that idling |
| `active_faults` | Active engine fault codes, most severe first |
| `driver_safety_scores` | 0-100 score per driver from harsh-driving events per 100 km |
| `recent_trips` | Latest trips for one vehicle |
## Design
```
Claude / any MCP client
│ stdio (JSON-RPC)
▼
server.py thin tool layer: descriptions written for the model, input validation
▼
store.py plain functions returning dicts: all business logic, unit-tested without MCP
▼
data.py SQLite schema + seeded synthetic fleet (same seed, same fleet)
```
Decisions worth calling out:
- **Logic is separate from the protocol.** `store.py` knows nothing about MCP, so swapping
SQLite for a live telematics API means replacing one module.
- **Errors tell the model what to do next.** An unknown vehicle id returns
*"Call list_vehicles to see valid ids"*, so the assistant recovers without the user.
- **Assumptions are returned with the answer.** `idling_report` includes the litres-per-hour
and fuel price it used, so the number can be challenged.
- **The data has a story.** Every fifth vehicle is seeded as a heavy idler and each driver
has a stable risk profile, so the tools have real outliers to find.
- **Read-only.** No tool writes to the database.
## Run it
```bash
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest -q # unit tests + an end-to-end test over stdio
python examples/demo_client.py # call the tools with no LLM involved
```
The database is created and seeded on first run. To regenerate it:
`fleet-mcp-seed --db fleet.db --vehicles 15 --days 30 --seed 42`.
### Use it from Claude Desktop
Add this to `claude_desktop_config.json`, with the path to your virtualenv's Python:
```json
{
"mcpServers": {
"fleet": {
"command": "/absolute/path/to/.venv/bin/python",
"args": ["-m", "fleet_mcp.server"],
"env": { "FLEET_DB": "/absolute/path/to/fleet.db" }
}
}
}
```
### Use it from Claude Code
```bash
claude mcp add fleet -- /absolute/path/to/.venv/bin/python -m fleet_mcp.server
```
## Questions to try
- Which vehicles idle the most, and what is that costing at $1.75 a litre?
- What should maintenance look at first this week?
- Which drivers in the Toronto depot need coaching, and why?
- Compare V005 with the rest of its depot.
## Limits and next steps
- Data is synthetic and time is frozen at a fixed reference date so results are reproducible.
- The safety score is a simple, explainable rule, not an industry standard.
- Next: a live-API adapter behind the `store` interface, and HTTP transport with auth for
multi-user deployments.
## License
MIT
TDQS
Scored across 6 tools
Each tool targets a distinct analytical view: fleet inventory, per-vehicle summary, fleet idle ranking, fleet fault triage, driver safety ranking, and per-vehicle trip detail. Minor overlap exists because vehicle_summary includes idle, fault, and trip metrics that idling_report, active_faults, and recent_trips cover in more depth, but scope and granularity differences keep selection clear.
All names use snake_case and are readable, but the set mixes verb-led names (list_vehicles, recent_trips) with noun-phrase names (vehicle_summary, idling_report, active_faults, driver_safety_scores). The inconsistency is stylistic rather than confusing, so agents can still infer intent.
Six tools is a well-scoped set for a fleet analytics server, with no redundant filler. Each tool maps to a common reporting question.
The read-only analytics surface covers fleet inventory, per-vehicle utilization, idling cost, fault triage, driver safety, and recent trip detail, which are the core queries for this domain. Minor gaps remain, such as a fleet-wide utilization overview or driver/vehicle metadata and maintenance history, but agents can work around them with the existing summaries.