# nyc-rent-check-mcp

An MCP server for NYC apartment hunters. Give it an address and it checks the city's public records: HPD violations, bed bug filings, 311 heat and noise complaints, and DOB complaints. Then it tells you what to worry about.

No API keys. Read-only. Data comes straight from [NYC Planning GeoSearch](https://geosearch.planninglabs.nyc) and [NYC Open Data](https://opendata.cityofnewyork.us).

## Install (Claude Code)

```bash
claude mcp add nyc-rent-check -- npx -y github:Sayemnyc/nyc-rent-check-mcp
```

For other MCP clients (Claude Desktop, Cursor, etc.), add this to the client's MCP config:

```json
{ "mcpServers": { "nyc-rent-check": { "command": "npx", "args": ["-y", "github:Sayemnyc/nyc-rent-check-mcp"] } } }
```

Requires Node 18+.

## Tools

| Tool | What it does |
| --- | --- |
| `lookup_building(address)` | Resolves an address to its BBL (tax lot) and BIN (building ID) using NYC Planning GeoSearch. |
| `building_report(address)` | Returns everything in one call: HPD violations (open and closed, by class A/B/C, plus rent-impairing and the latest open Class C items), annual bed bug filings, 311 heat/hot water and noise complaints from the last 24 months, and DOB complaints. |
| `red_flags(address)` | Gives a plain-English verdict (`High concern`, `Some concerns`, or `No major red flags`) and the top 3 concerns. |

If an address can't be resolved, the tool says why. For example: no house number, no NYC match, or the same address exists in more than one borough. In that last case, add the borough or ZIP.

## Example conversation

> **You:** I'm looking at an apartment at 2835 Barker Ave in the Bronx. Anything I should know?
>
> **Claude:** *(calls `red_flags`)* **High concern.** City records show serious, ongoing problems:
>
> 1. **326 heat/hot water complaints** to 311 in the last two years, the most recent on Oct 11, 2026.
> 2. **121 open Class C violations.** Class C means immediately hazardous. The newest is a broken self-closing entrance door, and there are open mouse and roach infestation orders in individual apartments.
> 3. **221 open Class B (hazardous) violations.**
>
> The landlord's bed bug filings show 1 infested unit in 2023–24 and none in the latest year. Ask how heat is handled in winter, and check the unit for pests during your viewing.
>
> **You:** Compare that to 350 5th Ave.
>
> **Claude:** *(calls `red_flags`)* That's the Empire State Building, which is commercial, so there's no HPD history at all. The only flags are 96 noise complaints (mostly commercial and street noise) and 1 open DOB complaint.

These numbers are live, so you'll see different counts when you run it.

## Data sources

All datasets were checked on data.cityofnewyork.us:

| Data | Dataset | Matched by |
| --- | --- | --- |
| HPD Housing Maintenance Code Violations | [`wvxf-dwi5`](https://data.cityofnewyork.us/d/wvxf-dwi5) | BIN |
| Bedbug Reporting (annual landlord filings) | [`wz6d-d3jb`](https://data.cityofnewyork.us/d/wz6d-d3jb) | BIN |
| 311 Service Requests, 2020 to present | [`erm2-nwe9`](https://data.cityofnewyork.us/d/erm2-nwe9) | BBL |
| DOB Complaints Received | [`eabe-havv`](https://data.cityofnewyork.us/d/eabe-havv) | BIN |

311 only records the tax lot (BBL), so on lots with several buildings the 311 counts cover the whole lot. HPD violation classes: **A** = non-hazardous, **B** = hazardous, **C** = immediately hazardous, **I** = info/order.

## Rate limits

Queries use server-side aggregation (`$select`/`$group`), so each report is 5 small requests plus 1 geocode. Responses are cached in memory for 10 minutes, so calling `building_report` and then `red_flags` on the same address doesn't re-fetch. The server backs off and retries on HTTP 429 or 5xx. If you're doing heavy use, you can set a free Socrata app token for higher limits:

```bash
claude mcp add nyc-rent-check -e SOCRATA_APP_TOKEN=yourtoken -- npx -y github:Sayemnyc/nyc-rent-check-mcp
```

## Development

```bash
npm install
npm test        # builds, then runs live tests against two real addresses
npm start       # runs the stdio server
```

## Caveats

Public records lag reality and miss a lot. A clean record isn't a guarantee, and a messy one in a 500-unit building may matter less than it looks. The `red_flags` weights are a simple heuristic, not legal or professional advice.

## License

MIT