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)

Related MCP server: Geotab ACE MCP Server

Setup

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

Configure credentials

Copy the example env file and fill in your credentials:

cp .env.example .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:

{
  "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

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

{
  "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):

{
  "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

Devices

Trips

Tachograph

Fuel

Diagnostics

Faults

Drivers

Audit

MyAdmin (separate platform)

These tools call Geotab's MyAdmin API, not MyGeotab. They need MyAdmin credentials (MYADMIN_USERNAME / MYADMIN_PASSWORD, falling back to the GEOTAB_* pair) on an account holding the MyAdminApiUser role, and they don't take the MyGeotab customer parameter.

The Device Management tools are read-only by design. No MyAdmin method that changes billing, ownership or provisioning is wrapped. Contact records (people's names, emails, phones, addresses) are never returned. Only the customer's company name is kept.

get_device_contracts inputs: forAccount? (omit to walk every account on the login), serialNos?, imeis? (≤1,000 each), devicePlanId? (-1 = all), fromDate? / toDate? (default: today UTC), showNoDatabaseOnly?, showShelfStockOnly?, database? (client-side, matches primary/owner/shared), enrich?, cursor?, pageSize? (default 50). It fetches at most 5 × 1,000-row API pages per call, then returns a cursor. Calls are paced to MyAdmin's published 1,250 requests / 15 min, with backoff on rate-limit responses.

Billing status is derived. MyAdmin returns no status string. The order of precedence is: terminated → termination pending → unactivated → pending/active by billingStartDate → active. billingStartDate is null for devices shipped before 2023-09-09, so a missing value doesn't mean "not billing". See deriveBillingStatus in src/tools/device-management.ts.

Development

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