# geotab-mcp

MCP server that exposes the MyGeotab API as AI-callable tools. Lets Claude query fleet data, device status, trips, tachograph files, fuel, diagnostics, faults, and driver information across multiple customer databases through natural language.

## Prerequisites

- Node.js 20+
- Geotab API credentials (username + password with access to customer databases)

## Setup

```bash
git clone <repo-url>
cd geotab-mcp
npm install
```

### Configure credentials

Copy the example env file and fill in your credentials:

```bash
cp .env.example .env
```

```env
GEOTAB_USERNAME=api.user@yourcompany.com
GEOTAB_PASSWORD=your-password
GEOTAB_SERVER=my.geotab.com
GEOTAB_TEST_DATABASE=your_test_database
```

### Multi-customer setup

Create a `geotab.config.json` in the project root to map friendly customer names to Geotab databases:

```json
{
  "customers": [
    { "name": "Example Customer", "database": "example_db" },
    { "name": "Another Customer", "database": "another_db", "server": "my3.geotab.com" }
  ]
}
```

One shared username/password (from `.env`) accesses all databases. The `server` field is optional — `mg-api-js` resolves the correct federated server automatically.

When `geotab.config.json` is absent, the server falls back to single-customer mode using `GEOTAB_DATABASE` from `.env`.

### Build

```bash
npm run build
```

## Using with Claude

### Claude Desktop

Add the server to your Claude Desktop config file:

- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "geotab": {
      "command": "node",
      "args": ["C:/absolute/path/to/geotab-mcp/dist/index.js"],
      "env": {
        "GEOTAB_USERNAME": "api.user@yourcompany.com",
        "GEOTAB_PASSWORD": "your-password",
        "GEOTAB_SERVER": "my.geotab.com"
      }
    }
  }
}
```

You can omit the `env` block if you have a `.env` file in the project directory.

### Claude Code (CLI)

Add the server to your Claude Code project settings (`.claude/settings.json` in the project root, or `~/.claude/settings.json` for global):

```json
{
  "mcpServers": {
    "geotab": {
      "command": "node",
      "args": ["C:/absolute/path/to/geotab-mcp/dist/index.js"],
      "env": {
        "GEOTAB_USERNAME": "api.user@yourcompany.com",
        "GEOTAB_PASSWORD": "your-password",
        "GEOTAB_SERVER": "my.geotab.com"
      }
    }
  }
}
```

Or add it interactively from Claude Code with `/mcp`.

Restart Claude Desktop or Claude Code after adding the config. The server should appear in the available tools list.

## Available tools

Every data tool takes a **required `customer`** parameter. Call `list_orgs` first to see available customers.

### Config
| Tool | Description |
|------|-------------|
| `list_orgs` | List configured customers, databases, and auth server |

### Devices
| Tool | Description |
|------|-------------|
| `search_devices` | Search devices by name, VIN, serial, group |
| `get_device` | Full device detail by ID |
| `get_device_status_info` | Live location, speed, driving state, current driver |
| `get_device_listening_mode` | Whether a GO device is in CAN/OBD **listen-only** mode (passively reads the bus) vs **active**, or **unknown** — with the supporting evidence. Select by deviceId, name, or serialNumber |

### Trips
| Tool | Description |
|------|-------------|
| `search_trips` | Trip summaries with distance, speed, driver |

### Tachograph
| Tool | Description |
|------|-------------|
| `search_tachograph_files` | List tacho files by upload date range |
| `get_tacho_last_upload` | Most recent tacho upload per device |
| `download_tacho_file` | Download binary data for a tacho file |

### Fuel
| Tool | Description |
|------|-------------|
| `get_fuel` | Fuel level (%) and fuel used (L) over time |

### Diagnostics
| Tool | Description |
|------|-------------|
| `get_device_health` | IOX, NFC, CAN C/D, voltage, comms health |
| `get_status_data` | Raw StatusData for any diagnostic |
| `list_diagnostics` | Discover diagnostic IDs in a database |

### Faults
| Tool | Description |
|------|-------------|
| `get_faults` | Fault codes / DTCs with severity |

### Drivers
| Tool | Description |
|------|-------------|
| `get_driver_assignment` | Current driver per device |
| `search_driver_changes` | Driver login/logout history |
| `list_drivers` | Driver roster lookup |

### Audit
| Tool | Description |
|------|-------------|
| `audit_iox_accessory` | Fleet-wide audit of IOX accessory fitment (e.g. IOX-GOTALK). Classifies each device as fitted, missing, or indeterminate |

## Development

```bash
npm run typecheck   # type-check without emitting
npm run build       # compile to dist/
npm test            # unit tests (mg-api-js mocked)
npm run test:integration  # live tests (requires credentials)
npm run test:all    # both
npm start           # run the server
```