@matchuplabs/nycfhv-mcp

MCP server that exposes the NYC FHV Intelligence API — real-time TLC for-hire-vehicle license verification and renewal-window lookups — as Claude, Cursor, Windsurf, and VS Code agent tools.

Data source: NYC TLC's For-Hire Vehicles - Active dataset, refreshed daily 4–7 PM ET. Public record under NY State FOIL.

Why this exists

Apps and AI agents that touch NYC for-hire transportation today can't verify a TLC license without scraping a manual portal. This MCP wraps a commercial-grade verification API so an agent can confirm "is this vehicle currently TLC-active?" as a single tool call before authorizing a livery rate, dispatching a Medicaid NEMT trip, or pre-binding insurance.

The API also correctly handles wheelchair-accessible (WAV) status — Socrata returns the WAV column as "WAV" / "PILOT" / absent (not "YES" / "NO"), and most wrappers silently misclassify the ~8,400-vehicle WAV cohort. This one doesn't.

Tools

| Tool | What it does | Cost | |---|---|---| | verify_tlc_vehicle | Verify an FHV by TLC license, DMV plate, or VIN. | 1 credit | | list_upcoming_renewals | Vehicles whose license expires in the next N days. | 5 credits / page | | subscribe_renewal_webhook | Daily push notifications for renewal-window deltas. | 0 to create, 1 / event |

verify_tlc_vehicle

Verify whether a NYC TLC for-hire vehicle is currently licensed. Read-only.

Inputs

| Param | Type | Required | Description | |---|---|---|---| | identifier | string | yes | TLC license (C05015 or 5545596), DMV plate (T438350C), or 17-char VIN. | | type | "auto" \| "license" \| "plate" \| "vin" | no | Override auto-detection. Default "auto". |

Auto-detection rules

• 17 alphanumeric chars → VIN
• One letter + five digits (e.g., C05015) → TLC license number
• Otherwise → DMV plate

Example response

{
  "data": {
    "active": true,
    "vehicle_license_number": "5545596",
    "name": "OPERATOR NAME",
    "license_type": "FHV",
    "expiration_date": "2026-08-14",
    "days_until_expiration": 95,
    "permit_license_number": "B03404",
    "dmv_license_plate_number": "T438350C",
    "vehicle_vin_number": "1FADP3K20JL215555",
    "wheelchair_accessible": false,
    "vehicle_year": 2018,
    "base_number": "B03404",
    "base_name": "UBER USA, LLC",
    "base_type": "Black Car"
  },
  "meta": {
    "source": "nyc-open-data/tlc-fhv-active/8wbx-tsch",
    "updated": "2026-05-11T22:14:00Z",
    "credits_remaining": 4998
  }
}

Error shape (any tool)

{
  "error": {
    "code": "not_found",
    "message": "No active TLC record matches that identifier.",
    "suggested_next_step": "Confirm the identifier with the operator or try a different type."
  }
}

list_upcoming_renewals

List vehicles whose license expires within the next N days. Read-only. Paginated.

Inputs

| Param | Type | Required | Description | |---|---|---|---| | days | integer (1–180) | yes | Renewal window from today, inclusive. | | base_number | string | no | TLC base filter (e.g., B03404 = Uber). | | wheelchair_accessible | boolean | no | true = WAV only, false = non-WAV only, omit for both. | | vehicle_year_max | integer | no | Max model year — fleet-aging targeting. | | page | integer | no | 1-indexed. Default 1. | | page_size | integer (10–100) | no | Default 50. |

Example response

{
  "data": [
    {
      "active": true,
      "vehicle_license_number": "5545596",
      "name": "OPERATOR NAME",
      "expiration_date": "2026-06-01",
      "days_until_expiration": 21,
      "wheelchair_accessible": true,
      "vehicle_year": 2017,
      "base_number": "B03404",
      "base_name": "UBER USA, LLC"
    }
  ],
  "meta": {
    "source": "nyc-open-data/tlc-fhv-active/8wbx-tsch",
    "updated": "2026-05-11T22:14:00Z",
    "page": 1,
    "page_size": 50,
    "total_count": 412,
    "credits_remaining": 4993
  }
}

subscribe_renewal_webhook

Subscribe a webhook URL to daily renewal-window deltas. Each day after the TLC dataset refresh, the API diffs newly-entered renewal-window vehicles against yesterday's snapshot and POSTs the delta. Events are HMAC-SHA256-signed via the signing_secret returned at creation.

Inputs

| Param | Type | Required | Description | |---|---|---|---| | webhook_url | string (HTTPS) | yes | Endpoint to receive daily POST events. | | days | integer (1–180) | no | Renewal window. Default 30. | | base_number | string | no | Filter to one TLC base. | | wheelchair_accessible | boolean | no | WAV-only or non-WAV-only filter. | | vehicle_year_max | integer | no | Max model year filter. | | description | string (≤200) | no | Human-readable label. |

Example response

{
  "data": {
    "id": "sub_01HXYZ...",
    "status": "active",
    "signing_secret": "whsec_...",
    "webhook_url": "https://example.com/fhv-webhook",
    "filter": { "days": 30, "base_number": "B03404" },
    "created_at": "2026-05-11T22:14:00Z"
  },
  "meta": {
    "source": "matchuplabs/fhv-intelligence/subscriptions"
  },
  "important": "Store the signing_secret securely — it is only returned once. Use it to verify the X-FHV-Signature header on incoming webhook events."
}

Install

1. Get an API key at matchuplabs.com (product: fhv-intelligence).
2. Add the config block below to your MCP host.
3. Restart the host. The three tools appear in the tool picker.

Claude Desktop

Config path: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).

{
  "mcpServers": {
    "nycfhv": {
      "command": "npx",
      "args": ["-y", "@matchuplabs/nycfhv-mcp"],
      "env": {
        "FHV_API_KEY": "mv_live_your_key_here"
      }
    }
  }
}

Cursor

Config path: ~/.cursor/mcp.json (global) or <project>/.cursor/mcp.json (per-project).

{
  "mcpServers": {
    "nycfhv": {
      "command": "npx",
      "args": ["-y", "@matchuplabs/nycfhv-mcp"],
      "env": {
        "FHV_API_KEY": "mv_live_your_key_here"
      }
    }
  }
}

VS Code (with Copilot MCP)

Config path: <project>/.vscode/mcp.json.

{
  "servers": {
    "nycfhv": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@matchuplabs/nycfhv-mcp"],
      "env": {
        "FHV_API_KEY": "mv_live_your_key_here"
      }
    }
  }
}

Windsurf

Config path: ~/.codeium/windsurf/mcp_config.json.

{
  "mcpServers": {
    "nycfhv": {
      "command": "npx",
      "args": ["-y", "@matchuplabs/nycfhv-mcp"],
      "env": {
        "FHV_API_KEY": "mv_live_your_key_here"
      }
    }
  }
}

Claude Code (CLI)

claude mcp add nycfhv -- npx -y @matchuplabs/nycfhv-mcp

Then set FHV_API_KEY in your shell or via claude mcp env config.

Environment

| Variable | Required | Default | |---|---|---| | FHV_API_KEY | yes | — | | FHV_BASE_URL | no | https://fhv.matchup.dev |

Development

npm install
FHV_API_KEY=mv_test_xxx npm run dev    # stdio server, requires a real key
npm run build
npm test

Links

• API docs
• Source (api-ventures monorepo)
• Report issues

License

MIT. © Matchup Labs.