Hiring a summer nanny? Payroll and taxes, handled.See how →

Skip to main content

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.

1

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 Key
2

Add to Claude Desktop

Open your Claude Desktop config file and add the NannyKeeper server. Replace nk_live_YOUR_KEY with your actual API key.

claude_desktop_config.jsonjson
// 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"
      }
    }
  }
}
3

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.

Example conversationtext
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_taxes

Calculate 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.

Parameters
statestring2-letter US state code (e.g., CA, NY)
annual_wagesnumberAnnual wages paid to the employee
pay_frequencystringweekly, biweekly, semimonthly, or monthly
check_threshold

Check if annual wages cross the IRS household employer threshold ($3,000 for 2026) and any state-specific thresholds.

Parameters
statestring2-letter US state code
annual_wagesnumberAnnual wages to check
tax_yearnumberTax year (default: current year)
preview_payroll

Dry-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.

Parameters
employer_idstringEmployer UUID from your account
employee_idstringEmployee UUID
pay_period_startstringStart date (YYYY-MM-DD)
pay_period_endstringEnd date (YYYY-MM-DD)
pay_datestringPay date (YYYY-MM-DD). Optional — server picks the earliest valid date if omitted.
pay_frequencystringweekly, biweekly, semimonthly, or monthly
voluntary_set_asideobjectOptional (v1.6.0+). Override or skip the employee's recurring voluntary set-aside rule for this paycheck only. Shape: { skip?: boolean, amount?: number }.
run_payroll

Run 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.

Parameters
employer_idstringEmployer UUID from your account
employee_idstringEmployee UUID to run payroll for
pay_period_startstringStart date (YYYY-MM-DD)
pay_period_endstringEnd date (YYYY-MM-DD)
pay_datestringPay 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_frequencystringweekly, biweekly, semimonthly, or monthly
payment_methodstringdirect_deposit, check, or cash (default: check)
confirm_large_payrollbooleanRequired for direct-deposit payrolls with total net pay >$5,000 or any single net pay >$3,000.
confirm_ach_debitbooleanRequired for first-ever DD payroll or when >30 days have elapsed since the last DD authorization.
voluntary_set_asideobjectOptional (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
Last updated: March 2026