Content
# nyc-restroom-mcp
Ask Claude "where's the nearest public bathroom?" and get a real answer.
This is an [MCP](https://modelcontextprotocol.io) server, a small plugin that
gives an AI assistant (like Claude Desktop or Claude Code) new abilities. This
one lets it search New York City's official public restroom data, live from
[NYC Open Data](https://opendata.cityofnewyork.us/). Once installed, you can
ask things like:
- "Find a public restroom near Union Square that's open right now."
- "Which restrooms near me are wheelchair accessible?"
- "Is the bathroom at Jaime Campiz Playground actually clean?" (it looks up
the latest NYC Parks inspection report)
It adds two tools:
| Tool | What it does |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `find_restrooms` | Lists open public restrooms near a location, closest first, with hours, accessibility, and changing-station info. |
| `get_restroom_status` | Looks up one restroom by name or coordinates, including its most recent NYC Parks inspection rating, where one exists. |
If you don't give it a location, it can detect yours automatically (details
below). Everything is read-only: it only ever fetches public city data.
## Install
You need [Node.js](https://nodejs.org) 20 or newer. No download or setup
beyond the snippet for your app.
**Claude Code** (one command):
```bash
claude mcp add nyc-restroom -- npx -y nyc-restroom-mcp
```
**Claude Desktop**: go to Settings -> Developer -> Edit Config and add this to
`claude_desktop_config.json`:
```json
{
"mcpServers": {
"nyc-restroom": {
"command": "npx",
"args": ["-y", "nyc-restroom-mcp"]
}
}
}
```
Any other MCP client works the same way: have it launch
`npx -y nyc-restroom-mcp` as a local (stdio) server.
## Good to know
- **Automatic location.** If you ask for nearby restrooms without saying
where you are, the server tries to figure it out: first from your device
(macOS only, if you `brew install corelocationcli` and grant it Location
Services access), otherwise a rough guess from your IP address. If neither
works, or you're outside NYC, it simply asks for explicit coordinates
instead of guessing wrong.
- **Privacy.** Location detection only happens when you omit coordinates,
and your location is never written to logs. Pass explicit coordinates and
no location lookup happens at all.
- **Live data.** Every answer comes straight from NYC Open Data (with a
short-lived in-memory cache), so results are as current as the city's own
records. Inspection reports only exist for restrooms run by NYC Parks;
library and other restrooms will honestly say no inspection data exists.
- **More detail.** The [docs/](docs/) directory covers the full
[tool reference](docs/tools.md), [location detection](docs/location.md),
[data sources](docs/data-sources.md), [configuration](docs/configuration.md),
and [security model](docs/security.md). The reasoning behind every design
decision lives in [DECISIONS.md](DECISIONS.md).
### Optional settings
Set these as environment variables if you need them (most people don't):
| Variable | Purpose |
| ------------------- | -------------------------------------------------------------------- |
| `SOCRATA_APP_TOKEN` | A free NYC Open Data app token, for higher rate limits. |
| `LOG_LEVEL` | `error`, `warn`, or `info` (default `info`). Logs go to stderr only. |
A few more exist for testing and advanced setups; see
[docs/configuration.md](docs/configuration.md).
## Contributing
Issues and pull requests are welcome at
[DanielOrtiz0220/nyc-restroom-mcp](https://github.com/DanielOrtiz0220/nyc-restroom-mcp).
Development uses [Bun](https://bun.sh) (1.1+):
```bash
git clone https://github.com/DanielOrtiz0220/nyc-restroom-mcp.git
cd nyc-restroom-mcp
bun install
bun test # full unit + end-to-end suite, runs completely offline
bun run typecheck # tsc --noEmit
bun run lint # eslint, zero warnings allowed
bun run build # compile src/ to dist/ (what the npm package ships)
```
To run your local copy inside an MCP client instead of the published package:
```bash
claude mcp add nyc-restroom -- bun "$(pwd)/src/index.ts"
```
Useful extras: `bun run test:live` runs one smoke test against the real NYC
Open Data API (needs network), and `bun test --coverage` reports coverage
(85%+ lines required on `src/lib/`). Before opening a PR, please make sure
`bun test`, `bun run typecheck`, and `bun run lint` all pass. The full
development guide (test architecture, project structure, invariants to
preserve) is in [docs/development.md](docs/development.md), and
[DECISIONS.md](DECISIONS.md) explains why things work the way they do.
## License
[MIT](LICENSE)
