sheet-and-flow-mcp

# Sheet & Flow Landlord Math (MCP server)

<!-- mcp-name: io.github.onyxaholguin-cyber/sheet-and-flow-mcp -->

Landlord and rental-property calculators as [Model Context Protocol](https://modelcontextprotocol.io) tools, so Claude, Cursor, VS Code or any MCP client does the math the same way every time instead of estimating it.

- **Offline and deterministic.** No network calls, no API keys, no data leaves your computer.
- **No dependencies.** Plain Node.js (18+), about 380 lines you can read.
- **Tested.** 552 randomized cases against an independent Python model, and the worked examples from the Sheet & Flow tutorials, on Node 18, 20 and 22 in CI. The rental math was also cross-checked against spreadsheet-recalculated (LibreOffice) deals before release.

## Tools

| Tool | What it answers |
|---|---|
| `rental_property_analysis` | Year-one NOI, monthly and annual cash flow, cap rate, cash-on-cash, DSCR, gross rent multiplier, break-even occupancy, expense ratio |
| `mortgage_payment` | Monthly principal and interest, total interest |
| `short_term_rental_analysis` | Airbnb/VRBO booked nights, stays, gross revenue, cash flow, RevPAR, what each booked night is worth, **break-even occupancy** and **break-even nightly rate** |
| `rent_late_fee` | Days late and the late fee: grace period, flat + percent + daily fees, a cap; optional Colorado / New York / Texas examples |
| `lease_renewal_notice` | Date the renewal or rent-increase notice must go out, 0-30/31-60/61-90 day window, status, next lease end |
| `irs_mileage_deduction_2026` | 2026 IRS standard mileage deduction (business 72.5¢ Jan–Jun, 76¢ Jul–Dec) |

Percentages are fractions (`0.25` = 25%). Dates are `YYYY-MM-DD`. A percentage passed as `7` instead of `0.07` is rejected with a clear message rather than silently computed.

## Install

**Claude Desktop (one click):** download `sheet-and-flow-mcp-<version>.mcpb` from the [latest release](https://github.com/onyxaholguin-cyber/sheet-and-flow-mcp/releases/latest) and open it.

**Any MCP client (stdio):** clone the repo and point your client at `server/index.js`:

```json
{
  "mcpServers": {
    "sheet-and-flow": { "command": "node", "args": ["/path/to/sheet-and-flow-mcp/server/index.js"] }
  }
}
```

It is also listed in the [official MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.onyxaholguin-cyber/sheet-and-flow-mcp`.

## Example

Ask: *"Airbnb deal: $350,000, 25% down at 7%, $185 a night, 62% occupancy, 14 blocked nights, 3.2-night stays, $95 cleaning fee, $85 cleaning cost, 15.5% host fee, 9% maintenance, $920/month fixed costs, $10,500 closing, $25,000 furnishing. Does it cash flow?"*

`short_term_rental_analysis` returns, among other fields:

```json
{ "monthlyCashFlow": -208.64, "keptPerBookedNight": 135.53, "breakEvenOccupancy": 0.6726, "breakEvenNightlyRate": 200.24 }
```

So the deal loses about $209 a month as quoted; it needs 67.3% occupancy at $185, or $200.24 a night at 62%. The same example is worked step by step in the [short-term rental calculator tutorial](https://onyxaholguin-cyber.github.io/sheet-and-flow/tutorials/short-term-rental-deal-analyzer-spreadsheet/).

## How the math works

Every formula is explained in a free tutorial:

- [Cap rate, cash-on-cash and DSCR](https://onyxaholguin-cyber.github.io/sheet-and-flow/tutorials/cap-rate-cash-on-cash-dscr/) and the [free rental deal calculator](https://onyxaholguin-cyber.github.io/sheet-and-flow/tools/rental-deal-calculator/)
- [Short-term rental break-even occupancy and nightly rate](https://onyxaholguin-cyber.github.io/sheet-and-flow/tutorials/short-term-rental-deal-analyzer-spreadsheet/)
- [Rent late fee calculator (grace period, cap, state examples)](https://onyxaholguin-cyber.github.io/sheet-and-flow/tutorials/rent-late-fee-calculator-spreadsheet/)
- [Lease renewal tracker and notice dates](https://onyxaholguin-cyber.github.io/sheet-and-flow/tutorials/lease-renewal-tracker-spreadsheet/)
- [IRS 2026 mileage log](https://onyxaholguin-cyber.github.io/sheet-and-flow/tutorials/irs-mileage-log-schedule-c-2026/) and the [mileage deduction calculator](https://onyxaholguin-cyber.github.io/sheet-and-flow/tools/mileage-deduction-calculator/)

## Prefer a spreadsheet?

The same math comes as finished Excel / Google Sheets workbooks from Sheet & Flow (paid; this server is free and MIT-licensed and doesn't need them):
[Short-Term Rental Deal Analyzer](https://sheetandflow.gumroad.com/l/short-term-rental-analyzer) ·
[Rental Property Deal Analyzer](https://sheetandflow.gumroad.com/l/rental-deal-analyzer) ·
[Landlord Tenant Toolkit](https://sheetandflow.gumroad.com/l/landlord-tenant-toolkit) ·
[Lease Renewal Tracker](https://sheetandflow.gumroad.com/l/lease-renewal-tracker) ·
[Freelancer Mileage Log](https://sheetandflow.gumroad.com/l/freelancer-mileage-log) ·
[Free Rental Cash Flow Calculator](https://sheetandflow.gumroad.com/l/free-rental-calculator)

## Development

```bash
npm test                       # node --test, no install step
python3 test/model.py          # regenerate fixtures from the independent Python model
python3 scripts/build_mcpb.py  # build dist/*.mcpb and dist/server.json
```

Releases: pushing a `v*` tag runs the tests, builds the `.mcpb`, attaches it to a GitHub release and publishes `server.json` to the MCP Registry with GitHub OIDC (no stored tokens).

## Disclaimer

Estimates for planning only. Not legal, tax or investment advice. The late-fee state examples are a summary of statute text as of October 2026; check current law, city rules and your lease before charging a fee.

MIT License © Sheet & Flow