# 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)