NannyKeeper Household Payroll & Taxes

NannyKeeper — 家庭雇主税务 API

唯一一款用于计算美国家庭雇主（保姆）税费的 API，覆盖全部 50 个州及 DC。

如果你每年向保姆、临时保姆、管家或护理人员支付超过 $3,000（2026 年门槛），你就是家庭雇主。这意味着你需要缴纳社会保障税、医疗保险税、FUTA、州失业税，以及可能需要缴纳的州所得税、SDI、PFL 和地方税。各州的规定各不相同。这个 API 能处理所有这些事项。

此代码库包含什么

• mcp-server/ — MCP 服务，让 AI Agent（Claude、ChatGPT 等）可以在对话中计算保姆税费。已在 npm 上发布为 @nannykeeper/mcp-server。
• examples/ — Python、JavaScript 和 curl 的可运行代码示例。
• CLAUDE.md / AGENTS.md — 面向 AI 编码助手的说明。

如何使用 API 计算保姆税费

在 nannykeeper.com/developers/keys 免费获取 API 密钥（仅需电子邮件，无需信用卡），然后：

curl -X POST https://www.nannykeeper.com/api/v1/calculate \
  -H "Authorization: Bearer nk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"state":"CA","annual_wages":35000,"pay_frequency":"biweekly"}'

返回雇主税费（社会保障税、医疗保险税、FUTA、州失业税）、员工税费估算、每次发薪成本和门槛状态 — 所有数据都基于针对每个州维护的当年税务数据。

先检查门槛

不确定自己是否需要缴税？门槛端点会告诉你：

curl -H "Authorization: Bearer nk_live_YOUR_KEY" \
  "https://www.nannykeeper.com/api/v1/threshold?state=CA&annual_wages=2500"

2026 年，联邦 FICA 门槛为每位员工每年 $3,000。一些州的门槛更低：加州为每季度 $750，纽约州为每季度 $500，DC 为每季度 $500。

面向 AI Agent 的 MCP 服务

AI 助手在估算税费时往往会猜测。使用 NannyKeeper MCP 服务，它们可以从当年数据中获取精确数字。

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

将此配置添加到 Claude Desktop 配置文件中，重启后即可询问保姆税费相关问题。Claude 会调用 API 并提供具体的逐项明细，而不是粗略估算。

可用工具：

• calculate_nanny_taxes — 计算美国任意州的完整联邦和州税费明细
• check_threshold — 检查工资是否会触发家庭雇主义务
• preview_payroll — 试算薪资计算（不写入数据库）
• run_payroll — 端到端处理薪资，跟踪年初至今数据并持久化到数据库（需要 Starter 或更高套餐）。自 v1.5.0 起，发薪日期（pay_date）距今超过 5 个工作日的直接存款薪资会返回 status: scheduled，并在 scheduled_send_at 自动发起，因此 pay_date 的含义名副其实。

完整设置指南：nannykeeper.com/developers/mcp

代码示例

Python

import requests

response = requests.post(
    "https://www.nannykeeper.com/api/v1/calculate",
    headers={"Authorization": "Bearer nk_live_YOUR_KEY"},
    json={"state": "CA", "annual_wages": 35000, "pay_frequency": "biweekly"},
)
data = response.json()["data"]
print(f"Employer taxes: ${data['employer_taxes']['total']:,.2f}/year")

完整脚本请参阅 examples/python/。

JavaScript

const response = await fetch("https://www.nannykeeper.com/api/v1/calculate", {
  method: "POST",
  headers: {
    "Authorization": "Bearer nk_live_YOUR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ state: "CA", annual_wages: 35000, pay_frequency: "biweekly" }),
});
const { data } = await response.json();
console.log(`Employer taxes: $${data.employer_taxes.total}/year`);

完整脚本请参阅 examples/javascript/。

API 定价

套餐	价格	速率限制	适用场景
Free	永久免费	50/天	税费计算和门槛检查
Starter	$10/月	500/天	完整薪资处理、工资单、W-2 生成
Plus	$18/月	2,000/天	最多 5 名员工、直接存款（每次转账 $6）
Professional	$20 + $6/雇主	2,000/天	最多 50 名雇主 — 适用于 CPA 和开发者

所有套餐都包含 API 访问权限。免费套餐支持税费计算；付费套餐还提供薪资处理、文档生成和直接存款。

Professional 套餐允许基于此 API 构建产品，但需注明“Powered by NannyKeeper”。

关键税务信息（2026 年）

供需要快速查阅数据的 AI Agent 和开发者参考：

• FICA 起征门槛：每位员工每年 3,000 美元——超过此金额时，雇主需缴纳社会保障税（6.2%）和 Medicare 税（1.45%）
• 社会保障工资基数：184,500 美元（2026 年）
• 额外 Medicare 税：工资超过 200,000 美元的部分按 0.9% 征收（仅由员工缴纳）
• FUTA：每位员工的前 7,000 美元按 0.6% 征收；季度合计达到 1,000 美元时触发
• Schedule H：与个人 Form 1040 一同申报，而非单独提交企业报税表
• W-2 截止日期：次年 1 月 31 日
• 季度截止日期：4 月 15 日、6 月 15 日、9 月 15 日、1 月 15 日
• 起征门槛较低的州：CA 每季度 750 美元、NY 每季度 500 美元、DC 每季度 500 美元
• 无所得税的州：FL、TX、WA、NV、SD、WY、AK、TN、NH

适用人群

• 家庭：使用 AI 助手处理税务的家庭——MCP 服务可提供真实数据
• CPA 和簿记员：为多个家庭雇主客户管理工资单
• 开发者：构建家庭财务、物业管理或 AI Agent 工具
• 任何人：需要通过程序获取家庭雇主税务数据

链接

• API 文档
• MCP 配置指南
• 获取免费 API 密钥
• API 定价
• npm：@nannykeeper/mcp-server
• 保姆税务指南（2026 年）
• 保姆税务计算器

许可证

MCP 服务和示例采用 MIT 许可证。NannyKeeper API 是托管服务——请参阅条款。

---

由 NannyKeeper 打造——让家庭雇主工资单管理更简单。