Enrolling in a Dependent Care FSA?How to claim up to $7,500
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.

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.

  1. In Claude, open Settings, then Connectors, and add a custom connector.
  2. Paste this URL and click Connect:
Connector URLtext
https://www.nannykeeper.com/api/v1/mcp
  1. Sign in to NannyKeeper, review what Claude can and can't do, and click Allow.
  2. 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.

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. To run payroll and get pay stubs, your household needs the Starter plan or higher.

Get API key
2

Add 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 Codebash
claude mcp add nannykeeper \
  --env NANNYKEEPER_API_KEY=nk_live_YOUR_KEY \
  -- npx -y @nannykeeper/mcp-server@latest

In Claude Desktop, add the server to your config file instead.

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": ["-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.

3

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.

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:                   $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.

Running payrolltext
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_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)
list_employees

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

Parameters
employer_idstringOptional. Only when one account manages several households.
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_idstringOptional. Leave it out to use the household your API key belongs to.
employee_idstringEmployee UUID, from list_employees
pay_period_startstringStart date (YYYY-MM-DD)
pay_period_endstringEnd date (YYYY-MM-DD)
pay_datestringPay date (YYYY-MM-DD). Optional. If you leave it out, we pick the earliest valid business day on or after the period end.
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 }.
reimbursementsarrayOptional (v1.18.0+). Up to 10 mileage, transit, parking or other lines paid with this paycheck: { type, amount, description?, miles?, rate_per_mile? }. For mileage send the miles and amount 0, and NannyKeeper prices them at the IRS rate it holds for the pay period and pay date, or at rate_per_mile or the household's own rate when lower, never above the IRS rate.
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_idstringOptional. Leave it out to use the household your API key belongs to.
employee_idstringEmployee UUID to run payroll for, from list_employees
pay_period_startstringStart date (YYYY-MM-DD)
pay_period_endstringEnd date (YYYY-MM-DD)
pay_datestringPay 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_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 }.
reimbursementsarrayOptional (v1.18.0+). Up to 10 mileage, transit, parking or other lines paid with this paycheck: { type, amount, description?, miles?, rate_per_mile? }. For mileage send the miles and amount 0, and NannyKeeper prices them at the IRS rate it holds for the pay period and pay date, or at rate_per_mile or the household's own rate when lower, never above the IRS rate.
get_payroll

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

Parameters
payroll_idstringOptional. A payroll ID from run_payroll. Leave it out to list payrolls.
employer_idstringOptional. Only when listing for one of several households.
list_payrolls

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

Parameters
employee_idstringOptional. Only payrolls that paid this employee, from list_employees.
pay_date_fromstringOptional. Earliest pay date (YYYY-MM-DD).
pay_date_tostringOptional. Latest pay date (YYYY-MM-DD).
limitnumberOptional. 1 to 100, default 25.
cursorstringOptional. next_cursor from the previous call, for the next page.
employer_idstringOptional.
get_pay_stub

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

Parameters
payroll_idstringThe payroll ID from run_payroll or get_payroll
employer_idstringOptional.
get_w2

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

Parameters
employee_idstringThe employee ID from list_employees
tax_yearnumberA tax year that has ended
copystringOptional. A, B, C, D, 1 or 2. Defaults to B.
employer_idstringOptional.
get_schedule_h

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

Parameters
tax_yearnumberA tax year that has ended
employer_idstringOptional.
get_quarter_taxes

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

Parameters
yearnumberThe tax year, for example 2026
quarternumberThe calendar quarter, 1 to 4
employer_idstringOptional.
record_tax_payment

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

Parameters
yearnumberThe tax year, for example 2026
quarternumberThe calendar quarter, 1 to 4
destinationstringfederal, or a state agency id from get_quarter_taxes
expected_amountnumberThe figure get_quarter_taxes showed, when that is what you paid
amountnumberWhat you actually paid, when it was different
payment_datestringOptional. YYYY-MM-DD, defaults to today
closes_filingbooleanOptional. With amount, for a state agency: that amount settles the filing
idempotency_keystringA new unique key per payment
employer_idstringOptional.
get_state_filing_status

Read your state agency accounts (unemployment, withholding, disability) with last four digits only, and whether each is registered, pending, required or not required.

Parameters
employer_idstringOptional.
get_autopilot

Read Autopilot (payroll that runs itself each payday) for one employee, or list active enrollments. Requires Plus or Pro.

Parameters
employee_idstringOptional. Leave it out to list enrollments.
employer_idstringOptional.
manage_autopilot

Pause, resume, skip or turn off an existing Autopilot enrollment. Turning Autopilot on happens in the dashboard. Requires Plus or Pro.

Parameters
employee_idstringEmployee UUID
actionstringpause, resume, skip, or disable
through_datestringOptional, skip only: skip every period up to this date (YYYY-MM-DD)
employer_idstringOptional.
void_payroll

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

Parameters
payroll_idstringThe payroll's id, from list_payrolls or get_payroll
confirmation_codestringOptional. Left out on the first call; the code it returns, once you have confirmed
reasonstringWith the code: why it is being voided
employer_idstringOptional.

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
Last updated: October 2026