How do I set up the NannyKeeper MCP server?
The NannyKeeper MCP server lets AI agents like Claude and ChatGPT calculate household employer taxes for all 50 US states during conversations. Install takes 30 seconds: get a free API key, add the config below, and you're done.
Connect from claude.ai, no API key
In Claude on the web, desktop or phone, you can connect your NannyKeeper account directly. You sign in to NannyKeeper and choose what Claude can do.
- In Claude, open Settings, then Connectors, and add a custom connector.
- Paste this URL and click Connect:
https://www.nannykeeper.com/api/v1/mcp- Sign in to NannyKeeper, review what Claude can and can't do, and click Allow.
- Ask Claude about your household payroll.
This URL connects Claude, ChatGPT, Claude Code and Codex. NannyKeeper turns away any other assistant. Use an API key for those.
What the connection can do
- Estimate taxes and check thresholds
- See employees, payrolls and quarterly taxes
- Preview a paycheck
- Record a check or cash payroll
- Record a tax payment, or void a payroll before money moves
- Get pay stubs and tax form links
- Pause, skip or turn off Autopilot
What it can't do
- Move money: no direct deposit payroll
- Resume or turn on Autopilot
- Connect a bank
- File or pay taxes for you
For those, use nannykeeper.com, or the MCP server below on your own API key.
Tax estimates work on any plan. Your employees, payroll and forms need the Starter plan or higher. To disconnect, revoke the "Claude connection" key in API Keys, or remove NannyKeeper in Claude. A connection ends on its own after 30 days. What Claude receives is in our privacy policy, Section 4.7.
Get a free API key
You need an API key to authenticate requests. The free tier gives you 50 calculations per day — no credit card required. To run payroll and get pay stubs, your household needs the Starter plan or higher.
Get API keyAdd it to Claude Code or Claude Desktop
In Claude Code, run this once in your terminal. Replace nk_live_YOUR_KEY with your API key. Add --scope user to use it in every project.
claude mcp add nannykeeper \
--env NANNYKEEPER_API_KEY=nk_live_YOUR_KEY \
-- npx -y @nannykeeper/mcp-server@latestIn Claude Desktop, add the server to your config file instead.
// Add to your Claude Desktop config file:
// macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
// Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"nannykeeper": {
"command": "npx",
"args": ["-y", "@nannykeeper/mcp-server@latest"],
"env": {
"NANNYKEEPER_API_KEY": "nk_live_YOUR_KEY"
}
}
}
}Finding NannyKeeper in the MCP registry does not add it to Claude Desktop. It shows up there only after you add this config or install the server's .mcpb bundle.
Start a conversation
In Claude Code, run /mcp to check the NannyKeeper tools are connected. In Claude Desktop, restart the app. Then ask about nanny taxes, and Claude calls NannyKeeper's tools for a line-by-line breakdown.
You: "How much would I owe in taxes if I pay my nanny
$35,000 per year in California?"
Claude: [calls calculate_nanny_taxes tool]
"Based on NannyKeeper's calculation, here's your breakdown
for a $35,000/year employee in California:
Employer taxes (your cost):
Social Security: $2,170.00
Medicare: $507.50
FUTA: $147.00
CA Unemployment + ETT: $245.00
Total: $3,069.50/year ($118.06/paycheck biweekly)
FUTA includes California's 2026 credit reduction of 1.5%.
Your total cost per paycheck: $1,464.21
($1,346.15 gross pay + $118.06 employer taxes)
This exceeds the $3,000 FICA threshold, so you are a
household employer and must file Schedule H."With a Starter plan, Claude can also run payroll. It finds your household and your employee with list_employees, shows you the paycheck from preview_payroll, and runs it only after you say yes. You never need to look up an ID.
You: "Nora worked 76 hours from Oct 26 to Nov 8.
Run Nora's payroll as a check."
Claude: [calls list_employees]
[calls preview_payroll]
"Here is Nora's paycheck before I run it: gross $1,900.00,
net $1,469.84, your cost $2,106.15. Run it?"
You: "Yes."
Claude: [calls run_payroll]
[calls get_payroll]
[calls get_pay_stub]
"Done. The payroll is complete and Nora's pay stub is attached."Available tools
calculate_nanny_taxesCalculate employer and employee tax obligations for a household employee in any US state. Returns Social Security, Medicare, FUTA, state unemployment, income tax, and per-paycheck breakdown.
| state | string | 2-letter US state code (e.g., CA, NY) |
| annual_ | number | Annual wages paid to the employee |
| pay_ | string | weekly, biweekly, semimonthly, or monthly |
check_thresholdCheck if annual wages cross the IRS household employer threshold ($3,000 for 2026) and any state-specific thresholds.
| state | string | 2-letter US state code |
| annual_ | number | Annual wages to check |
| tax_ | number | Tax year (default: current year) |
list_employeesList your household's employees and return your employer_id. Call it first: it gives the employee_id the payroll tools need, and shows what is still missing for payroll. Requires Starter+ subscription.
| employer_ | string | Optional. Only when one account manages several households. |
preview_payrollDry-run payroll for a household employee — returns the full tax breakdown, net pay, and employer costs without creating a record. Use to validate your request before calling run_payroll. Requires Starter+ subscription.
| employer_ | string | Optional. Leave it out to use the household your API key belongs to. |
| employee_ | string | Employee UUID, from list_ |
| pay_ | string | Start date (YYYY-MM-DD) |
| pay_ | string | End date (YYYY-MM-DD) |
| pay_ | string | Pay date (YYYY-MM-DD). Optional. If you leave it out, we pick the earliest valid business day on or after the period end. |
| pay_ | string | weekly, biweekly, semimonthly, or monthly |
| voluntary_ | object | Optional (v1.6.0+). Override or skip the employee's recurring voluntary set-aside rule for this paycheck only. Shape: { skip?: boolean, amount?: number }. |
| reimbursements | array | Optional (v1.18.0+). Up to 10 mileage, transit, parking or other lines paid with this paycheck: { type, amount, description?, miles?, rate_ |
run_payrollRun payroll end-to-end: creates, approves, and processes (or schedules) the payroll in a single call. Response reflects the finalized state (processing / pending_funding / completed / scheduled as of v1.5.0) — no UI intervention needed. When pay_date is more than 5 business days in the future on a DD payroll, returns scheduled + scheduled_send_at and the payroll auto-fires at that timestamp. Requires Starter+ subscription.
| employer_ | string | Optional. Leave it out to use the household your API key belongs to. |
| employee_ | string | Employee UUID to run payroll for, from list_ |
| pay_ | string | Start date (YYYY-MM-DD) |
| pay_ | string | End date (YYYY-MM-DD) |
| pay_ | string | Pay date (YYYY-MM-DD). Optional. If you leave it out, we pick the earliest valid business day on or after the period end, allowing for direct deposit lead time. Past-deadline dates return 400 with next_ |
| pay_ | string | weekly, biweekly, semimonthly, or monthly |
| payment_ | string | direct_ |
| confirm_ | boolean | Required for direct-deposit payrolls with total net pay >$5,000 or any single net pay >$3,000. |
| confirm_ | boolean | Required for first-ever DD payroll or when >30 days have elapsed since the last DD authorization. |
| voluntary_ | object | Optional (v1.6.0+). Override or skip the employee's recurring voluntary set-aside rule for this paycheck only. Shape: { skip?: boolean, amount?: number }. |
| reimbursements | array | Optional (v1.18.0+). Up to 10 mileage, transit, parking or other lines paid with this paycheck: { type, amount, description?, miles?, rate_ |
get_payrollRead one payroll by ID, or list your payrolls. Shows status, dates, and each employee's gross pay, every deduction, net pay and employer taxes. Requires Starter+ subscription.
| payroll_ | string | Optional. A payroll ID from run_ |
| employer_ | string | Optional. Only when listing for one of several households. |
list_payrollsList your payrolls, newest first, with status, dates, totals and the employees each one paid. Filter by employee and by pay date, for example to ask what you paid your nanny last time or for your last three payrolls. Requires Starter+ subscription.
| employee_ | string | Optional. Only payrolls that paid this employee, from list_ |
| pay_ | string | Optional. Earliest pay date (YYYY-MM-DD). |
| pay_ | string | Optional. Latest pay date (YYYY-MM-DD). |
| limit | number | Optional. 1 to 100, default 25. |
| cursor | string | Optional. next_ |
| employer_ | string | Optional. |
get_pay_stubGet the pay stub PDF for each employee on a paid payroll, the same stub you download in the dashboard. It arrives as an attached PDF file. Requires Starter+ subscription.
| payroll_ | string | The payroll ID from run_ |
| employer_ | string | Optional. |
get_w2Get a download link for one copy of an employee's W-2, for a tax year that has ended. It is the same W-2 you download in the dashboard. The assistant gives you a link on nannykeeper.com and you open it in your browser; it works for 15 minutes. The tool never sends the PDF to the assistant, because a W-2 shows a full Social Security number. You generate the W-2 in the dashboard first; this tool never generates one. Requires a Starter+ subscription or a W-2 Only purchase.
| employee_ | string | The employee ID from list_ |
| tax_ | number | A tax year that has ended |
| copy | string | Optional. A, B, C, D, 1 or 2. Defaults to B. |
| employer_ | string | Optional. |
get_schedule_hGet a download link for your Schedule H, for a tax year that has ended. It is the same form you download in the dashboard. The assistant gives you a link on nannykeeper.com and you open it in your browser; it works for 15 minutes. NannyKeeper does not file it for you. Requires Starter+ subscription.
| tax_ | number | A tax year that has ended |
| employer_ | string | Optional. |
get_quarter_taxesGet a quarter's tax figures as your Taxes page shows them: what to pay or file, to whom, and by when, with the optional federal estimated payment for the IRS installment, each state agency's amount and due date, and your state and local lines. Where NannyKeeper cannot give a figure yet, the assistant tells you why instead of saying $0. NannyKeeper does not file or pay for you. Requires Starter+ subscription.
| year | number | The tax year, for example 2026 |
| quarter | number | The calendar quarter, 1 to 4 |
| employer_ | string | Optional. |
record_tax_paymentTell NannyKeeper you paid a quarter's tax to the IRS or a state agency, as "I've paid this" on your Taxes page does, and once that covers what you owe it stops reminding you. The assistant reads the quarter first, then records the figure it showed you, or the amount you actually paid. If the figure changed since it read the quarter, it shows you the new one and asks before trying again. NannyKeeper does not send the payment for you. Requires Starter+ subscription.
| year | number | The tax year, for example 2026 |
| quarter | number | The calendar quarter, 1 to 4 |
| destination | string | federal, or a state agency id from get_ |
| expected_ | number | The figure get_ |
| amount | number | What you actually paid, when it was different |
| payment_ | string | Optional. YYYY-MM-DD, defaults to today |
| closes_ | boolean | Optional. With amount, for a state agency: that amount settles the filing |
| idempotency_ | string | A new unique key per payment |
| employer_ | string | Optional. |
get_state_filing_statusRead your state agency accounts (unemployment, withholding, disability) with last four digits only, and whether each is registered, pending, required or not required.
| employer_ | string | Optional. |
get_autopilotRead Autopilot (payroll that runs itself each payday) for one employee, or list active enrollments. Requires Plus or Pro.
| employee_ | string | Optional. Leave it out to list enrollments. |
| employer_ | string | Optional. |
manage_autopilotPause, resume, skip or turn off an existing Autopilot enrollment. Turning Autopilot on happens in the dashboard. Requires Plus or Pro.
| employee_ | string | Employee UUID |
| action | string | pause, resume, skip, or disable |
| through_ | string | Optional, skip only: skip every period up to this date (YYYY-MM-DD) |
| employer_ | string | Optional. |
void_payrollVoid a payroll that has not moved any money: a draft, or a scheduled direct deposit whose bank debit has not started. The assistant first shows you the payroll and asks; nothing is voided until you say yes. A payroll with money already on the move, or a completed one, is voided in the app, and the assistant gives you the link. Requires Starter+ subscription.
| payroll_ | string | The payroll's id, from list_ |
| confirmation_ | string | Optional. Left out on the first call; the code it returns, once you have confirmed |
| reason | string | With the code: why it is being voided |
| employer_ | string | Optional. |
Other MCP clients use an API key
Any other MCP client connects with your API key, not the connector URL. The server uses standard stdio transport, so the config is the same as Claude Desktop's: point the client at npx -y @nannykeeper/mcp-server@latest with your API key in the environment.
Getting new tools
The setup above runs @nannykeeper/mcp-server@latest, so each time your client starts the server it uses the newest release. If you added the server without @latest, npx can keep running an older copy: add @latest to the package name in your config, then restart your client.
Need more than calculations?
The free tier covers tax calculations. Upgrade to run payroll, generate pay stubs and W-2s, and process direct deposit — all via the same API.
View API pricing