NannyKeeper Household Payroll & Taxes MCP server

NannyKeeper — Household Employer Tax API

The only API for calculating US household employer (nanny) taxes. Covers all 50 states + DC.

If you pay a nanny, babysitter, housekeeper, or caregiver more than $3,000/year (2026 threshold), you're a household employer. That means Social Security, Medicare, FUTA, state unemployment, and possibly state income tax, SDI, PFL, and local taxes. The rules are different in every state. This API handles all of it.

What's in this repo

• mcp-server/ — MCP server so AI agents (Claude, ChatGPT, etc.) can calculate nanny taxes in conversation. Published on npm as @nannykeeper/mcp-server.
• examples/ — Working code examples in Python, JavaScript, and curl.
• CLAUDE.md / AGENTS.md — Instructions for AI coding assistants.

How to calculate nanny taxes with an API

Get a free API key (email only, no credit card) at nannykeeper.com/developers/keys, then:

curl -X POST https://www.nannykeeper.com/api/v1/calculate \
  -H "Authorization: Bearer nk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"state":"CA","annual_wages":35000,"pay_frequency":"biweekly"}'

Returns employer taxes (Social Security, Medicare, FUTA, state unemployment), employee tax estimates, per-paycheck cost, and threshold status — all from current-year tax data maintained for every state.

Check the threshold first

Not sure if you even need to pay taxes? The threshold endpoint tells you:

curl -H "Authorization: Bearer nk_live_YOUR_KEY" \
  "https://www.nannykeeper.com/api/v1/threshold?state=CA&annual_wages=2500"

For 2026, the federal FICA threshold is $3,000/year per employee. Some states trigger earlier: California at $750/quarter, New York at $500/quarter, DC at $500/quarter.

MCP server for AI agents

AI assistants guess at tax calculations. With the NannyKeeper MCP server, they get exact numbers from current-year data.

{
  "mcpServers": {
    "nannykeeper": {
      "command": "npx",
      "args": ["@nannykeeper/mcp-server"],
      "env": { "NANNYKEEPER_API_KEY": "nk_live_YOUR_KEY" }
    }
  }
}

Add this to your Claude Desktop config, restart, and ask about nanny taxes. Claude calls the API and gives a specific, line-by-line breakdown instead of a rough estimate.

Tools available:

• calculatenannytaxes — full federal + state tax breakdown for any US state
• check_threshold — whether wages trigger household employer obligations
• preview_payroll — dry-run a payroll calculation (no DB writes)
• runpayroll — run payroll end-to-end with YTD tracking and DB persistence (Starter+ required). As of v1.5.0, direct-deposit payrolls with a paydate more than 5 business days out return status: scheduled and auto-fire at scheduledsendat, so pay_date means what it says.

Full setup guide: nannykeeper.com/developers/mcp

Code examples

Python

import requests

response = requests.post(
    "https://www.nannykeeper.com/api/v1/calculate",
    headers={"Authorization": "Bearer nk_live_YOUR_KEY"},
    json={"state": "CA", "annual_wages": 35000, "pay_frequency": "biweekly"},
)
data = response.json()["data"]
print(f"Employer taxes: ${data['employer_taxes']['total']:,.2f}/year")

See examples/python/ for the full script.

JavaScript

const response = await fetch("https://www.nannykeeper.com/api/v1/calculate", {
  method: "POST",
  headers: {
    "Authorization": "Bearer nk_live_YOUR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ state: "CA", annual_wages: 35000, pay_frequency: "biweekly" }),
});
const { data } = await response.json();
console.log(`Employer taxes: $${data.employer_taxes.total}/year`);

Shortened. The full README is on GitHub.