io.github.DanielOrtiz0220/nyc-restroom-mcp

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 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/ 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.

License

MIT