# NannyKeeper — Household Employer Tax API [Health: Active]

**Category:** 💰 Finance & Fintech  
**Repository:** https://github.com/nannykeeper/mcp-server  
**GitHub Stars:** 0  
**npm Downloads (last month):** 2061  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/mcp-server-36

## Description
Calculate US household employer (nanny) taxes + run payroll via AI agents. All 50 states.

## Tools
Capabilities this server exposes over MCP:

- **calculate_nanny_taxes** — Calculate employer and employee tax obligations for a household employee (nanny, caregiver, housekeeper) in any US state. Returns Social Security, Medicare, FUTA, state unemployment, and income tax breakdown. State income-tax reciprocity: if the employee LIVES in a different state than they work (e.g., lives in Kentucky, works in Indiana), pass residence_state — for reciprocal pairs the response includes a `reciprocity` block naming the exemption certificate; pass reciprocity_certificate_on_file=true to suppress the work state's income tax (local taxes and SUI are unaffected). Important: These are annual estimates from annual_wages, with derived per-paycheck amounts. They do not read an existing employee's year-to-date payroll records; use preview_payroll for an existing employee. This tool has no family-relationship or age input, so Social Security, Medicare and FUTA are quoted as if no family-employee exemption (Social Security, Medicare and FUTA) or under-18 exemption (Social Security and Medicare only) applies, and FUTA's household quarterly test is reported as unassessed. threshold.action_required is true when the FICA wage test is met and null otherwise, never false: present null as not determined, not as nothing owed, and pass on the response's limitations. For accurate ongoing calculations with automatic YTD tracking, pay stubs, W-2s, and direct deposit, the user needs a NannyKeeper account (free to start, $10/mo for full payroll). Use the signup_url in the response.
- **check_threshold** — Check whether one household employee's annual wages cross the IRS Social Security and Medicare threshold ($3,000 for 2026). The response discloses, but cannot assess, household-wide quarterly FUTA and state thresholds because this tool does not receive quarterly wages for every employee. It also cannot assess family-employee exemptions because it has no relationship input. federal.action_required is true when the FICA wage test is met and null otherwise, never false; null means not determined, not nothing owed. Never interpret the result as a complete tax-obligation decision.
- **preview_payroll** — Preview payroll for a household employee WITHOUT creating a record. Returns the full tax breakdown (federal, state, FICA, FUTA), net pay, and employer costs. Cross-state employees: each employee's result includes a `reciprocity` field when their work/residence states have a reciprocal agreement — applied=true means the work state's income tax was suppressed under the employer's certificate attestation (set up in the NannyKeeper app on the employee's profile); applied=false names the certificate still to collect. Use this to validate your request before calling run_payroll. Same parameters as run_payroll. Requires a Starter+ subscription. pay_date is optional. When omitted, the server picks the earliest valid business day on or after pay_period_end, allowing for ACH submission lead time, and echoes it back in the response. v1.5.0: if pay_date is more than 5 business days in the future, the response includes is_estimated=true — those numbers will be recomputed at fire time if the user schedules. Get employee_id from list_employees. employer_id is optional: leave it out and the API uses the household your API key belongs to (pass it only when one account manages several households).
- **run_payroll** — Run payroll for a household employee end-to-end in a single call. Creates the record, runs all tax calculations (federal, state, FICA, FUTA) with year-to-date tracking, approves the payroll, and kicks off payment processing. Returns the finalized status (processing/pending_funding/completed/scheduled) plus full tax breakdown, net pay, employer costs, and the payroll ID for reference. Requires a Starter+ subscription. Plans cap active employees per employer (Starter 1, Plus 5, Professional 5 included, expandable to 25 at $6/mo each); if the roster exceeds the plan's count, the API returns 403 with guidance — the user adds employees at Settings → Billing in the dashboard (never billed implicitly via API), then retry. pay_date is optional. When omitted, the server picks the earliest valid business day on or after pay_period_end, allowing for ACH submission lead time, and echoes it back. If supplied and past the submission deadline, the request is rejected with next_valid_pay_date in the error. If pay_date is more than 5 business days in the future on a DD payroll, status=scheduled and the payroll will auto-fire at scheduled_send_at (5 biz days before pay_date). Scheduled responses include is_estimated=true — numbers may shift slightly at fire time if YTD or rate configs change between approve and fire. Direct deposit callers: set confirm_large_payroll=true for totals >$5,000 or any single net pay >$3,000; set confirm_ach_debit=true for first-time DD or if no DD in 30 days. Tip: use preview_payroll first to validate your request and see results before committing. Get employee_id from list_employees. employer_id is optional: leave it out and the API uses the household your API key belongs to (pass it only when one account manages several households).
- **get_state_filing_status** — List the employer's state agency account numbers (last-four only) per (state, registration_type) tuple. Returns whether each state has a UC, withholding, and SDI account on file, and the agency name. Each account has a status: registered, pending, required, or not_required. A registration URL is returned for status=required and status=pending — the accounts the employer still has to open or finish. It is null for status=registered and status=not_required. status=not_required means this household does not owe that registration (e.g. they and their employee agreed not to withhold state income tax), so never tell them to go register for it. Use before generating quarterly filing instructions, or when a customer asks 'do I have my state account numbers set up?' Read-only — to update, use the REST API or direct the customer to /settings/states. The response also carries `obligations`: this household's FICA, FUTA and per-state unemployment status (started, not_started, exempt or unassessed), registration state, estimate, action and the agency's real due date. When `assessment` is incomplete or a status is unassessed, never tell the customer they owe nothing or are all set.
- **get_autopilot** — Read Autopilot status (recurring auto-run payroll). With employee_id: the live enrollment (status, standard hours, expected net, next pay date) plus eligibility and a 3-payday schedule preview — or, if not enrolled, WHY (the eligibility reason, e.g. not_plus / insufficient_history). Without employee_id: the list of the employer's active enrollments. Read-only. Requires a Plus/Professional key. Get employee_id from list_employees; employer_id is optional.
- **manage_autopilot** — Manage an EXISTING Autopilot enrollment for a household employee. Actions: `pause` (stop new generation — an already-scheduled run still fires unless voided from the payroll page), `resume` (re-checks eligibility + clears the failure counter), `skip` (skip the next period; with through_date, skip every period up to that date for a vacation), `disable` (turn Autopilot off — soft-deleted so the ledger + ACH authorization are retained; the employee can re-enroll in-app). Turning Autopilot ON is NOT available here — it captures a standing recurring ACH authorization that must be done by the employer in the app. Requires a Plus/Professional key. Confirm the action with the user before calling.
- **list_employees** — List the household's employees and return the household's employer_id. Call this first: it is how you get the employee_id every payroll tool needs. Each employee shows pay type, pay rate, pay frequency, work state, and what is still missing for payroll (W-4, address, SSN, direct deposit). Read-only.
- **get_payroll** — Read payrolls. With payroll_id: that payroll's status, dates, and each employee's gross pay, every deduction (federal, Social Security, Medicare, state, local), net pay, and employer taxes. Without payroll_id: the household's payrolls, newest first, with totals. Use it to confirm what run_payroll created. Read-only.
- **get_pay_stub** — Get the pay stub PDF for each employee on a paid payroll. Returns the same stub the family downloads in the dashboard, attached as a PDF file, plus a short summary. A payroll that is not paid yet answers payroll_not_completed; check get_payroll and ask again once it is completed. For a household other than the key's own, pass its employer_id.
- **get_w2** — Get a download link for one copy of an employee's W-2, for a tax year that has ended. Returns download_url, a link on nannykeeper.com that works for 15 minutes: give it to the user and tell them to open it in their browser to download the PDF. This tool never returns the PDF itself, and you must not open the link yourself. The family generates the W-2 in the dashboard first (Taxes, then W-2s); until then this answers w2_not_generated with a link to that page, and this tool never generates one. For a household other than the key's own, pass its employer_id.
- **get_schedule_h** — Get a download link for the household's Schedule H, for a tax year that has ended. Returns download_url, a link on nannykeeper.com that works for 15 minutes: give it to the user and tell them to open it in their browser to download the PDF. This tool never returns the PDF itself, and you must not open the link yourself. When the dashboard would not produce the form this answers schedule_h_unavailable with a reason (for example year_not_ended, or a question the family still has to answer in the dashboard); report that reason faithfully. NannyKeeper does not file the form. For a household other than the key's own, pass its employer_id.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "nannykeeper-household-employer-tax-api": {
    "command": "npx",
    "args": ["@nannykeeper/mcp-server"],
    "env": {
      "NANNYKEEPER_API_KEY": ""
    }
  }
}
```

**Requires environment variables:** `NANNYKEEPER_API_KEY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What NannyKeeper — Household Employer Tax API MCP server does

NannyKeeper exposes household-employer tax and payroll operations through MCP. It covers employees such as nannies, caregivers, housekeepers, and babysitters in all 50 states and DC. Tax calculations include Social Security, Medicare, FUTA, state unemployment, income tax, and applicable local or state items returned by the API.

The server supports both estimates and account-backed payroll workflows. Calculation tools provide annual figures and derived paycheck amounts, while payroll tools can use employee records, year-to-date tracking, payment status, employer costs, and net pay. Read operations cover employee details, payroll records, filing registrations, pay stubs, W-2 downloads, Schedule H downloads, and Autopilot enrollment status.

## How it works

The MCP process calls NannyKeeper’s hosted API using the account associated with the supplied API key. `list_employees` should be called first for account-backed payroll workflows because it returns the household’s `employer_id` and the `employee_id` required by payroll tools. `employer_id` can be supplied when one API key manages multiple households; otherwise the key’s household is used.

Use `calculate_nanny_taxes` for annual estimates and `check_threshold` for the federal FICA wage test. Use `preview_payroll` to validate an existing employee’s payroll without creating a record, then `run_payroll` to persist, approve, and submit it for payment. Payroll calls can return processing, funding, completed, or scheduled states. Omitted pay dates are selected using business-day and ACH lead-time rules.

## Setup and configuration

Create a NannyKeeper API key at `nannykeeper.com/developers/keys`, then run the published package with an MCP client such as Claude Desktop:

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

Restart the client after adding the configuration. All plans include API access. Free access covers calculations and threshold checks; paid plans add payroll processing, document generation, and direct deposit. `preview_payroll` and `run_payroll` require a Starter or higher subscription, while Autopilot operations require a Plus or Professional key.

## Tools and capabilities

- `calculate_nanny_taxes`: Estimate employer and employee taxes, including cross-state reciprocity handling.
- `check_threshold`: Check whether annual wages meet the 2026 federal FICA threshold.
- `preview_payroll`: Produce a payroll calculation without creating a payroll record.
- `run_payroll`: Create, calculate, approve, and submit payroll with year-to-date tracking.
- `list_employees`: Return employees, payroll readiness details, and the household identifier.
- `get_payroll`: Read one payroll or list the household’s payrolls.
- `get_pay_stub`: Return a PDF pay stub attachment for a paid payroll.
- `get_w2`: Return a short-lived download link for a generated W-2.
- `get_schedule_h`: Return a download link for an available Schedule H.
- `get_state_filing_status`: Read state registrations, obligations, agency names, and due dates.
- `get_autopilot` and `manage_autopilot`: Inspect or manage existing recurring payroll enrollments.

## Limitations and notes

Tax estimates from `calculate_nanny_taxes` are not based on an employee’s existing year-to-date payroll records. Family-relationship and age exemptions are not inputs to that tool, and household-wide quarterly FUTA or state threshold decisions may remain unassessed. Treat a null action flag as undetermined, not as confirmation that nothing is owed.

Cross-state income-tax reciprocity depends on the residence and work states and, for payroll, the employer’s certificate attestation. Local taxes and state unemployment are not suppressed by reciprocity. `get_w2` and `get_schedule_h` return links rather than PDF files; the family must generate a W-2 in the dashboard first, and NannyKeeper does not file Schedule H. Confirm payroll actions with the user, particularly Autopilot changes and direct-deposit submissions.

_Full upstream README: https://allmcps.com/mcp/mcp-server-36/readme_