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.
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.
Get API KeyAdd to Claude Desktop
Open your Claude Desktop config file and add the NannyKeeper server. Replace nk_live_YOUR_KEY with your actual API key.
// 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": ["@nannykeeper/mcp-server"],
"env": {
"NANNYKEEPER_API_KEY": "nk_live_YOUR_KEY"
}
}
}
}Start a conversation
Restart Claude Desktop, then ask about nanny taxes. Claude will call NannyKeeper's tools to give a specific, 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: $42.00
CA Unemployment: $119.00
Total: $2,838.50/year ($109.17/paycheck biweekly)
Your total cost per paycheck: $1,455.94
($1,346.15 gross pay + $109.17 employer taxes)
This exceeds the $3,000 FICA threshold, so you are a
household employer and must file Schedule H."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_wages | number | Annual wages paid to the employee |
| pay_frequency | 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_wages | number | Annual wages to check |
| tax_year | number | Tax year (default: current year) |
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_id | string | Employer UUID from your account |
| employee_id | string | Employee UUID |
| pay_period_start | string | Start date (YYYY-MM-DD) |
| pay_period_end | string | End date (YYYY-MM-DD) |
| pay_date | string | Pay date (YYYY-MM-DD). Optional — server picks the earliest valid date if omitted. |
| pay_frequency | string | weekly, biweekly, semimonthly, or monthly |
| voluntary_set_aside | 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 }. |
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_id | string | Employer UUID from your account |
| employee_id | string | Employee UUID to run payroll for |
| pay_period_start | string | Start date (YYYY-MM-DD) |
| pay_period_end | string | End date (YYYY-MM-DD) |
| pay_date | string | Pay date (YYYY-MM-DD). Optional — server computes the earliest valid date from today + ACH lead time if omitted. Past-deadline dates return 400 with next_valid_pay_date in the error. |
| pay_frequency | string | weekly, biweekly, semimonthly, or monthly |
| payment_method | string | direct_deposit, check, or cash (default: check) |
| confirm_large_payroll | boolean | Required for direct-deposit payrolls with total net pay >$5,000 or any single net pay >$3,000. |
| confirm_ach_debit | boolean | Required for first-ever DD payroll or when >30 days have elapsed since the last DD authorization. |
| voluntary_set_aside | 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 }. |
Works with other MCP clients too
The server uses standard stdio transport. Any MCP-compatible client works — not just Claude Desktop. Same config pattern: point the client at npx @nannykeeper/mcp-server with your API key in the environment.
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