mcp-nychousing

MCP server for NYC housing data over NYC Open Data (the Socrata / SODA API). Built for tenant organizers, housing-court legal-aid intake, and Right-to-Counsel orgs: pull a building's HPD violations and complaints, find out who actually owns it (to serve papers), map everything else registered under that owner or agent's name, check HPD litigation against the landlord, and look up marshal-executed evictions.

It wraps six city datasets and normalizes their raw columns (novdescription, violationstatus, registrationid, court_index_number, and so on) into documented tool outputs.

Tools

borough accepts Manhattan, Bronx, Brooklyn, Queens, or Staten Island (also MN/BX/BK/QN/SI or the codes 1 to 5). violation_class is one of A (non-hazardous), B (hazardous), C (immediately hazardous), I (informational). since is an ISO date (YYYY-MM-DD).

Related MCP server: Dilix MCP

Data source and grounding

• Base URL: https://data.cityofnewyork.us/resource/<dataset-id>.json

• Auth: none. SODA is keyless. An optional Socrata app token (see below) only raises the per-IP rate limit.

• Response: list and aggregate queries return a bare JSON array. Errors return { "error": true, "message": "..." }.

• Query language: SoQL via $select, $where, $group, $order, $limit, with upper(...) and like for string matching and || for the first/last-name concatenation in landlord_portfolio. All user text is escaped (a single quote becomes two) before it reaches a query.

Dataset ids and column notes:

Field map (raw column to normalized output)

Install

No build step. Runs directly on tsx.

git clone https://github.com/haksanlulz/mcp-nychousing.git
cd mcp-nychousing
npm install

App token (optional)

Every tool works with no token. If you make heavy or bursty use, a free Socrata app token raises the rate limit. Create one from the developer settings on your NYC Open Data account. Docs: https://dev.socrata.com/docs/app-tokens.html

Expose it as NYC_APP_TOKEN and it is sent as the X-App-Token header:

export NYC_APP_TOKEN=your-token-here   # macOS / Linux
setx NYC_APP_TOKEN your-token-here      # Windows (new shells)

The token is never logged.

MCP client config

Point your MCP client at index.ts via tsx. Use an absolute path.

{
  "mcpServers": {
    "nychousing": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/mcp-nychousing/index.ts"]
    }
  }
}

Add an "env": { "NYC_APP_TOKEN": "your-token-here" } block only if you want the higher rate limit.

Example

Call building_violations with { "house_number": "1520", "street": "Sedgwick Avenue", "borough": "Bronx", "open_only": true, "limit": 1 }:

{
  "query": {
    "house_number": "1520",
    "street": "Sedgwick Avenue",
    "borough": "BRONX",
    "open_only": true,
    "violation_class": null,
    "since": null
  },
  "summary": { "total_matching": 128, "by_class": { "A": 21, "B": 74, "C": 33 } },
  "returned": 1,
  "results": [
    {
      "violation_id": "19051745",
      "apartment": "2D",
      "class": "C",
      "description": "HMC ADM CODE: ... ABATE THE INFESTATION CONSISTING OF MICE ...",
      "current_status": "NOTICE OF ISSUANCE SENT TO TENANT",
      "is_open": true,
      "rent_impairing": false,
      "inspection_date": "2026-07-04T00:00:00.000",
      "nov_type": "Original"
    }
  ]
}

The counts are illustrative and move as the city updates the data. The summary counts every match server-side; results is the most recent limit of them.

Then take a name from who_owns output and reverse it. Call landlord_portfolio with { "name": "WFHA 1520 SEDGWICK LP" }:

{
  "query": { "name": "WFHA 1520 SEDGWICK LP", "borough": null },
  "found": true,
  "summary": { "contact_matches": 1, "distinct_registrations": 1, "buildings_found": 1 },
  "note": "Contacts reflect HPD registration filings. The same landlord may file each building under a separate LLC; officer and agent person names often connect what the LLC names hide.",
  "returned": 1,
  "buildings": [
    {
      "registration_id": "221729",
      "building_id": "108415",
      "building_address": "1520 SEDGWICK AVENUE",
      "borough": "BRONX",
      "zip": "10453",
      "bin": "2009171",
      "last_registration_date": "2025-09-05T00:00:00.000",
      "registration_end_date": "2026-09-01T00:00:00.000",
      "matched_contacts": [
        { "type": "CorporateOwner", "organization": "WFHA 1520 SEDGWICK LP", "person_name": null }
      ]
    }
  ]
}

A single-building LLC like this one is itself the common NYC pattern; searching an officer or agent person name from the same who_owns output is how you connect the buildings the per-building LLC names hide.

Address matching

There is no geocoding here. Address matching is literal against how HPD stores addresses:

• Street names are stored uppercase. The server uppercases and trims your street input and matches it as a substring (upper(streetname) like '%YOUR STREET%'). So Sedgwick, sedgwick avenue, and SEDGWICK AVE all match SEDGWICK AVENUE, but a very short input can over-match (5 St would also hit 125 St). Pass the fuller street name when you can.

• House number is matched exactly (uppercased), so 1520 is not 1516-1520. Multi-address buildings can register under a range.

• Borough disambiguates same-numbered streets across boroughs, so it is required for the building tools. Litigations store a numeric borough code; evictions mix borough and county spellings (Brooklyn and Kings, Manhattan and New York, Staten Island and Richmond), and the borough filter expands to all of them.

• landlord_portfolio matches names the same way: uppercase substring against corporationname, firstname, lastname, and the firstname || ' ' || lastname concatenation (so a pasted person_name from who_owns works). LIKE wildcards (%, _) in your input are escaped. Pass the fullest name you have; a short fragment like SMITH or LLC over-matches, and the response says how many contact records matched before any cap.

• who_owns, landlord_portfolio, landlord_litigation, and the datasets themselves reflect HPD filings, which can lag reality. Confirm anything you intend to act on (for example a name to serve) before relying on it.

Develop

npm test         # vitest, fetch mocked (no network)
npm run smoke    # one live call per tool against SODA (keyless, no setup)
npm run typecheck

License

MIT. See LICENSE. Data from NYC Open Data (public City of New York data) served via the Socrata SODA API. Unofficial, not affiliated with the City of New York, HPD, or Socrata.