HyperTrack MCP Server

A Model Context Protocol (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):

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

HTTP Mode (for Dashboard Integration)

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

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

Or from a local installation:

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

# 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