nyc-restroom-mcp
Ask Claude "where's the nearest public bathroom?" and get a real answer.
This is an MCP 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. 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 20 or newer. No download or setup beyond the snippet for your app.
Claude Code (one command):
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:
{
"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 corelocationcliand 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/ directory covers the full tool reference, location detection, data sources, configuration, and security model. The reasoning behind every design decision lives in 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.
Contributing
Issues and pull requests are welcome at DanielOrtiz0220/nyc-restroom-mcp.
Development uses Bun (1.1+):
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:
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, and
DECISIONS.md explains why things work the way they do.