# calcuris-mcp

![npm version](https://img.shields.io/npm/v/calcuris-mcp)
![license](https://img.shields.io/npm/l/calcuris-mcp)

An MCP (Model Context Protocol) server that exposes the tax engines behind
[Calcuris](https://calcuris.com) — real 2026 US income tax & paycheck math, US
state property tax, Canadian federal + provincial income tax, Australian
income tax & stamp duty, and UK dividend tax. No API key, no network calls:
every number is computed locally from data sourced from the IRS, Tax
Foundation, CRA/Revenu Québec, the ATO and state revenue offices, and HMRC.

## Quick Start

Run directly with `npx` — no install required.

### Claude Desktop / Claude Code

Add to your MCP config (`claude_desktop_config.json` or `.mcp.json`):

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

### Cursor

Add to `.cursor/mcp.json`:

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

## Tools

Every response includes a `source` note and a `reference_url` pointing to the
live calculator on [calcuris.com](https://calcuris.com) that uses the same
engine.

| Tool | Description | Example call | Example response (excerpt) |
|---|---|---|---|
| `us_income_tax` | US federal (2026 IRS brackets, post-OBBBA) + estimated state income tax, with a full progressive bracket breakdown. | `{ "grossIncome": 95000, "filingStatus": "single", "stateCode": "CA" }` | `{ "federalTax": 12070, "stateTax": 4758.42, "totalTax": 16828.42, "marginalRate": 0.22, "takeHome": 78171.58 }` |
| `us_paycheck` | US take-home pay per pay period: federal withholding, Social Security, Medicare (+ Additional Medicare), state tax, net pay. | `{ "payType": "salary", "annualSalary": 80000, "payFrequency": "biweekly", "filingStatus": "single", "stateCode": "TX" }` | `{ "net": { "annual": 65110, "perPeriod": 2504.23 }, "federal": { "annual": 8770 }, "socialSecurity": { "annual": 4960 } }` |
| `us_property_tax` | Annual/monthly property tax from a home value and either a custom rate or a state's real 2026 effective rate. | `{ "homeValue": 450000, "stateCode": "TX" }` | `{ "annualTax": 6300, "monthlyTax": 525, "effectiveRatePct": 1.4 }` |
| `ca_income_tax` | Canadian federal + provincial/territorial income tax, CPP/QPP (+ CPP2/QPP2), EI/QPIP, and net take-home pay. Optional `compareAllProvinces`. | `{ "grossIncome": 75000, "provinceCode": "ON", "rrspContribution": 0 }` | `{ "federalTax": 8468.74, "provincialTax": 3696.06, "netIncome": 57465.69 }` |
| `au_income_tax` | Australian resident income tax (2025-26 ATO brackets) + Medicare levy, Medicare Levy Surcharge, LITO offset, HELP/HECS repayment. | `{ "taxableIncome": 95000, "privateHospitalCover": true, "hasHelpDebt": false }` | `{ "incomeTax": 19288, "medicareLevy": 1900, "totalTax": 21188, "takeHome": 73812 }` |
| `au_stamp_duty` | Australian state/territory stamp duty, including first-home-buyer concessions and the foreign purchaser surcharge. Optional `compareAllStates`. | `{ "propertyValue": 750000, "stateCode": "NSW", "firstHomeBuyer": false, "foreignResident": false, "principalResidence": true }` | `{ "baseDuty": 28162.5, "totalDuty": 28162.5, "effectiveRate": 3.755 }` |
| `uk_dividend_tax` | UK dividend tax with HMRC's stacking method (dividends sit on top of other income), tapered Personal Allowance, £500 dividend allowance, year-over-year comparison. | `{ "otherIncome": 40000, "dividends": 15000, "year": "2026/27" }` | `{ "dividendTax": 2741.25, "totalTax": 8227.25, "extraVsPrior": 290 }` |

Each tool's `inputSchema` documents every field (types, enums, defaults) and
is discoverable via `tools/list` — see the source in
[`src/index.ts`](./src/index.ts) for the full parameter set.

## Data sources & freshness

All engines target **tax year 2026** (UK: 2026/27, with 2025/26 comparison
built in). Rates and brackets are sourced from:

- **US** — IRS Rev. Proc. 2025-32 (federal brackets, standard deduction,
  Child Tax Credit), SSA/IRS FICA wage base and rates, Tax Foundation (state
  income tax brackets and property tax effective rates), state revenue
  offices.
- **Canada** — CRA (federal brackets, BPA, CPP/CPP2), Revenu Québec (QPP,
  QPIP, Quebec abatement), provincial finance ministries.
- **Australia** — ATO (2025-26 individual tax rates, Medicare levy, LITO,
  HELP/HECS repayment thresholds), state and territory revenue offices
  (stamp duty schedules and first-home-buyer concessions).
- **UK** — HMRC (Personal Allowance, dividend allowance, Income Tax bands and
  dividend rates for 2025/26 and 2026/27).

These are the same datasets that power the live calculators:

- [calcuris.com](https://calcuris.com)
- [US income tax calculator](https://calcuris.com/us/income-tax-calculator/)
- [US paycheck calculator](https://calcuris.com/us/paycheck-calculator/)
- [Canada income tax calculator](https://calcuris.com/ca/income-tax-calculator/)
- [Australia stamp duty calculator](https://calcuris.com/au/stamp-duty-calculator/)

## Disclaimer

Results are **estimates for guidance only** and do not constitute tax,
legal, or financial advice. Tax situations vary by individual (local taxes,
deductions, credits, and edge cases are not exhaustively modeled). Always
confirm figures with a qualified tax professional or the relevant government
authority before making financial decisions.

## Development

```bash
npm install
npm run build   # compiles src/ → dist/ with tsc
npm test        # spawns the built server and runs the smoke test
```

## License

MIT © 2026 tresor4k