@matchuplabs/nycfhv-mcp

@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

• Get an API key at matchuplabs.com (product: fhv-intelligence).
• Add the config block below to your MCP host.
• 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.