# marketcal

An **MCP server** that gives AI agents *correct* trading-day and settlement math.
LLMs are unreliable at "is the market open today?" and "what's the T+1 settlement date?" —
this gets it exactly right, with no API key and no external calls.

| Tool | Does |
| --- | --- |
| `is_trading_day` | Is a date a trading day? (weekend/holiday aware, with reason) |
| `next_trading_day` / `previous_trading_day` | Nearest trading day after/before a date |
| `settlement_date` | T+N settlement date (advance N trading days; T+1 is the modern default) |
| `trading_days_between` | Count trading days in an inclusive date range |
| `market_holidays` | List an exchange's holidays for a given year |

**Exchanges:** `NYSE`, `NASDAQ` (US), `LSE` (London), `XETRA` (Frankfurt), `GENERIC` (weekends only).

## Why it's correct

Holidays are **computed from each exchange's rules** — nth-weekday-of-month, Good Friday via the
Gregorian Easter algorithm, and the exchange's weekend-observation rules (e.g. US: Saturday →
Friday, Sunday → Monday; UK substitute days; XETRA closes Christmas Eve & New Year's Eve). No
hardcoded date tables to rot — it stays right for any year.

## Use it

```bash
npm install && npm run build && npm start
# or: npm run dev   (no build step)
npm run inspect      # try the tools in the MCP Inspector
```

**Connect to Claude Desktop / Cursor:**

```json
{
  "mcpServers": {
    "marketcal": {
      "command": "npx",
      "args": ["-y", "mcp-marketcal"]
    }
  }
}
```

Then ask: *"Using marketcal, what's the T+1 settlement date for a trade on 2026-07-02 on NYSE?"*
→ `2026-07-06` (July 3 is the observed Independence Day holiday, July 4–5 is the weekend).

## Notes & scope

- Covers full-day market closures. Early-close (half) days are not modelled in v0.1.
- All dates are calendar dates in `YYYY-MM-DD` (UTC), no intraday/timezone logic.
- `settlement_date` advances **trading days** (the standard settlement convention).
- Roadmap: more exchanges (TSX, Euronext, JPX, HKEX), early-close days, and a hosted HTTP +
  usage-billed tier (x402 / Stripe) for high-volume agents.

## License

MIT