npm package: @hypertrack/mcp-server
Description: HyperTrack MCP Server - Query your HyperTrack account through AI assistants
Latest version: 0.1.46

# HyperTrack MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that lets you query your HyperTrack account through AI assistants like Claude, ChatGPT, Gemini, or custom AI agents.

## Quick Start

### Claude Desktop

Add this to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "hypertrack": {
      "command": "npx",
      "args": ["-y", "@hypertrack/mcp-server"],
      "env": {
        "HYPERTRACK_ACCOUNT_ID": "your-account-id",
        "HYPERTRACK_SECRET_KEY": "your-secret-key"
      }
    }
  }
}
```

Get your Account ID and Secret Key from the [HyperTrack Dashboard](https://dashboard.hypertrack.com/setup).

### HTTP Mode (for Dashboard Integration)

Run the MCP server as an HTTP service with Streamable HTTP transport:

```bash
HYPERTRACK_ACCOUNT_ID=your-account-id \
HYPERTRACK_SECRET_KEY=your-secret-key \
npx -y hypertrack-mcp-http
```

Or from a local installation:

```bash
HYPERTRACK_ACCOUNT_ID=your-account-id \
HYPERTRACK_SECRET_KEY=your-secret-key \
PORT=3000 \
node node_modules/@hypertrack/mcp-server/build/http.js
```

The server will listen on `http://127.0.0.1:3000/mcp` by default. Set `HOST=0.0.0.0` to listen on all interfaces.

## Available Tools

### Orders
| Tool | Description |
|------|-------------|
| `list_orders` | List orders with filters (status, worker, date, etc.) |
| `get_order` | Get order details, timeline, and tracking data |
| `get_order_webhooks` | Get webhook events for an order |
| `estimate_order` | Estimate route distance and duration |
| `get_candidate_workers` | Find available workers for an order |

### Workers
| Tool | Description |
|------|-------------|
| `list_workers` | List workers with status and summary stats |
| `get_worker` | Get worker location, device, and timeline |

### Routes
| Tool | Description |
|------|-------------|
| `list_routes` | List routes with order sequences |
| `get_route` | Get route details with polyline and stops |

### Places
| Tool | Description |
|------|-------------|
| `list_places` | List delivery zones and destinations |
| `get_place` | Get place geofence and metadata |

### Devices
| Tool | Description |
|------|-------------|
| `list_devices` | List tracked devices |
| `get_device` | Get device location and status |
| `get_device_history` | Get device location history |

### Geotags
| Tool | Description |
|------|-------------|
| `list_geotags` | List proof-of-delivery geotags |
| `get_geotag` | Get geotag details |

### Visits
| Tool | Description |
|------|-------------|
| `list_visits` | List geofence entry/exit events |
| `get_visit` | Get visit duration and details |

### Geofences
| Tool | Description |
|------|-------------|
| `list_geofences` | List geographic boundaries |
| `get_geofence` | Get geofence geometry and visits |

### Account
| Tool | Description |
|------|-------------|
| `get_account_usage` | Get API usage statistics |

## Configuration

| Environment Variable | Required | Description |
|---------------------|----------|-------------|
| `HYPERTRACK_ACCOUNT_ID` | Yes | Your HyperTrack Account ID |
| `HYPERTRACK_SECRET_KEY` | Yes | Your HyperTrack Secret Key |
| `HYPERTRACK_API_BASE_URL` | No | Override API base URL |
| `PORT` | No | HTTP server port (default: 3000) |
| `HOST` | No | HTTP server bind address (default: 127.0.0.1) |
| `CORS_ORIGIN` | No | Allowed CORS origin (default: *) |

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Run tests (requires Node 18+)
npm test

# Watch mode for development
npm run dev

# Test with MCP Inspector
npx @modelcontextprotocol/inspector node build/index.js
```

## Example Queries

Once connected, you can ask your AI assistant questions like:

- "How many orders are active right now?"
- "Show me all completed orders from today"
- "Where is worker John?"
- "What's the ETA for order ORD-123?"
- "List all devices that are currently tracking"
- "Show me the delivery geotags from this week"
- "What's our API usage this month?"
- "Find the closest workers to this order"

## Requirements

- Node.js 18 or later
- HyperTrack account with API credentials

## License

MIT