# parknyc-mcp

MCP server for [ParkNYC](https://www.parknycapp.com/) (Flowbird) -- manage your NYC parking sessions, vehicles, and zones from any MCP client (Claude Code, Claude Desktop, etc.).

> **Note:** The Flowbird consumer API is undocumented. This server was built by reverse-engineering the [ParkNYC web app](https://my.nyc.flowbirdapp.com) JavaScript bundles. No public API docs exist.

## Setup

### 1. Install and build

```bash
git clone <repo-url> parknyc-mcp
cd parknyc-mcp
npm install
npm run build
```

### 2. Get your session cookies

The API authenticates via browser cookies. You need three: `PHPSESSID`, `server`, and `user`.

1. Open [my.nyc.flowbirdapp.com](https://my.nyc.flowbirdapp.com) in Chrome and log in. **Check "Keep me logged in"** to extend cookie lifetime from ~30 minutes to days/weeks.
2. Open DevTools (`Cmd+Option+I`) and go to the **Network** tab
3. Filter for `customer/get` and refresh the page
4. Click the `customer/get` request
5. Under **Request Headers**, find the **Cookie** line
6. Copy the full value -- it will look something like:
   ```
   server=.apachen2; PHPSESSID=abc123...; user=def456...
   ```

> **Important:** Do not include the `g_state` cookie if present -- it contains JSON braces that break the config file. You only need `PHPSESSID`, `server`, and `user`.

### 3. Configure your MCP client

#### Claude Code

Add a `.mcp.json` file to your project root:

```json
{
  "mcpServers": {
    "parknyc": {
      "command": "node",
      "args": ["/path/to/parknyc-mcp/dist/index.js"],
      "env": {
        "PARKNYC_COOKIES": "server=.apachen2; PHPSESSID=your_session_id; user=your_user_cookie"
      }
    }
  }
}
```

#### Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "parknyc": {
      "command": "node",
      "args": ["/path/to/parknyc-mcp/dist/index.js"],
      "env": {
        "PARKNYC_COOKIES": "server=.apachen2; PHPSESSID=your_session_id; user=your_user_cookie"
      }
    }
  }
}
```

### 4. Session expiry

Cookies expire periodically. If you checked "Keep me logged in", they should last days to weeks. Without it, sessions expire in ~30 minutes. When you start getting `401` errors, repeat step 2 to get fresh cookies and update your config.

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `PARKNYC_COOKIES` | Yes | Full cookie string from browser (must include `PHPSESSID`, `server`, `user`) |
| `PARKNYC_LANGUAGE` | No | Language code for API responses (default: `en`) |

## Available Tools

### Read

| Tool | Description |
|------|-------------|
| `get_account` | Get your account profile (name, email, phone, address) |
| `get_active_sessions` | Get currently active/ongoing parking sessions |
| `get_parking_history` | Get past parking sessions with pagination |
| `get_order` | Get details of a specific parking order by ID |
| `get_vehicles` | List all registered vehicles |
| `search_zone` | Search for a parking zone by number |
| `get_zone_info` | Get zone details (facility ID or POS number) |
| `get_bookmarks` | Get saved/favorite parking locations |
| `get_payment_accounts` | Get payment methods on file (cards, e-wallet) |

### Write

| Tool | Description |
|------|-------------|
| `start_parking` | Start a new parking session at a zone |
| `stop_parking` | Stop an active parking session early |
| `extend_parking` | Extend an active parking session |
| `cancel_parking` | Cancel a parking order |
| `add_vehicle` | Register a new vehicle |
| `delete_vehicle` | Remove a vehicle from your account |
| `add_bookmark` | Save a parking zone as a favorite |
| `delete_bookmark` | Remove a saved favorite |

## Example Usage

```
> Show my parking history from this week
> Do I have any active parking sessions?
> What vehicles are on my account?
> Search for zone 12345
> How much have I spent on parking this month?
> Start 15 minutes of parking at zone 12345 with my car
```

## How It Works

The Flowbird/ParkNYC web app at `my.nyc.flowbirdapp.com` is a PHP-backed Angular SPA. This MCP server mimics the browser's API calls:

- **Auth:** Three cookies (`PHPSESSID` for PHP session, `server` for load balancer affinity, `user` for the auth identity token)
- **Headers:** `X-MPP-Brand: parknyc` on every request
- **Params:** `platform=nyc`, `version=2.0.21+1792`, and `rt=<timestamp>` on every request
- **History:** Uses `/api/search/order/` with `x-api-caller: customer` header
- **Parking:** Two-step flow -- `order/create` (proposal) then `order/confirm` (payment)

## Limitations

- **No programmatic login:** The login endpoint requires reCAPTCHA, so cookies must be obtained manually from a browser session
- **Cookie expiry:** PHP sessions and the `user` cookie expire; you'll need to refresh them periodically
- **Start parking:** The `start_parking` tool needs the zone's `usertype` value which varies by zone. This is still being refined and may not work for all zones
- **Rate limits:** Rapid API calls may trigger 503 responses from the server

## License

MIT