Irs Taxpayer Mcp

---

⚠️ 免责声明：此工具提供的估算仅用于教育和信息参考，不构成税务、法律或财务建议。请务必咨询合格的税务专业人士。

法律声明：本软件按“原样”提供，不附带任何形式的保证。作者和贡献者均非税务专业人士、注册会计师（CPA）、注册代理人或律师。使用本软件不会建立律师与客户、CPA 与客户或受托关系。税法经常变化，并且因司法管辖区而异。计算结果可能存在错误或遗漏，也可能未反映最新的立法变更。您须对自己的报税决定承担全部责任。作者不承担因使用本软件而造成的任何损害。完整法律声明请参阅 DISCLAIMER.md。

为什么选择此 MCP？

报税季令人倍感压力。您需要处理 W-2、1099、扣除额和抵免额，还要弄清楚该逐项扣除还是采用标准扣除。您搜索“2025 年 SALT 扣除限额”，却找到 10 篇说法互相矛盾的文章。

此软件包提供一个确定性的本地税务引擎，并提供两种使用方式。直接使用本地 CLI 命令即可收集、验证、导入并计算受支持的税务信息，无需调用 MCP 客户端或模型。MCP 服务允许 AI 助手调用同一引擎，但输入云托管 MCP 客户端的税务信息可能会由该客户端的模型提供商处理。无需 IRS 登录或 SSN。

其中包含适用于 TY2025 的 OBBB 条款模型、联邦税率档位、部分抵免额和扣除额，以及明确支持的州税处理流程。不支持的州税计算会直接拒绝处理，而不会采用粗略的最高税率估算。

🔒 隐私架构

层	设计
确定性引擎	在本地运行，不进行运行时网络调用
直接使用 intake、validate 和 plan 命令	不连接 MCP、不调用模型、不收集遥测数据，也不自动持久化数据
本地信息文件	严格采用带版本的 JSON 格式，不含身份信息字段，最大 1 MiB；在 POSIX 系统上权限为 0600
MCP 服务	不发送或存储纳税人数据
MCP 客户端和模型	隐私取决于所选的宿主和模型提供商；提示词和工具参数可能会离开本机
身份验证	无需 SSN、IRS 登录或纳税人身份信息
IRS 公开数据	在本地打包并进行版本管理
源代码	开源 MIT 代码，计算过程可审计

⚡ 快速入门

选项 A：直接本地模式（推荐用于纳税人事实信息）

输入任何税务事实信息前，先安装一次：

npm install --global irs-taxpayer-mcp

运行本地引导式问卷。它不会启动 MCP 或调用模型：

irs-taxpayer-mcp intake --output taxpayer-facts.json

或者创建并编辑严格格式的本地模板：

irs-taxpayer-mcp template --output taxpayer-facts.json
irs-taxpayer-mcp validate --facts taxpayer-facts.json

通过确定性引擎直接计算：

irs-taxpayer-mcp plan --facts taxpayer-facts.json
irs-taxpayer-mcp plan --facts taxpayer-facts.json --json

新建的事实信息文件在 POSIX 系统上的权限模式为 0600。在 Windows 上，CLI 会拒绝现有符号链接，但依赖当前用户的文件系统权限。除非明确指定 --force，否则不会替换现有文件。导入的 JSON 大小限制为 1 MiB，会拒绝符号链接和未知字段，也不接受姓名、SSN、地址、雇主 ID 或账号。

使用 npx 可能会在执行前下载公共软件包，但直接命令不会通过网络发送事实信息文件或其内容。

选项 B：供 AI 助手使用的 MCP 模式

MCP 服务不会发起网络请求，也不会存储任何纳税人数据。不过，在 MCP 客户端中输入的事实信息可能会由该客户端的模型提供商处理。如果需要全程在本地处理，请使用直接本地模式或使用本地模型的 MCP 客户端。

MCP 第 1 步：添加到 AI 助手

将以下内容添加到 MCP 客户端配置中：

Claude Desktop（~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "irs-taxpayer": {
      "command": "npx",
      "args": ["-y", "irs-taxpayer-mcp"]
    }
  }
}

Kiro（.kiro/settings/mcp.json）：

{
  "mcpServers": {
    "irs-taxpayer": {
      "command": "npx",
      "args": ["-y", "irs-taxpayer-mcp"]
    }
  }
}

Cursor：在 Cursor 的 MCP 设置中使用相同格式。

MCP 第 2 步：重启 AI 助手

保存配置后，重启应用。MCP 服务将自动下载并连接。

MCP 第 3 步：询问支持的税务问题

客户端模型会将自然语言转换为工具参数。除非所选 MCP 宿主和模型符合你的隐私要求，否则不要在此输入真实的纳税人事实信息：

• “计算我的联邦税：收入 15 万美元，夫妻联合申报，有 2 个孩子”
• “比较收入 20 万美元时加利福尼亚州、得克萨斯州和华盛顿州的情况”
• “我是年收入 8 万美元的自由职业者：季度预缴税要交多少？”
• “我符合哪些税收抵免资格？AGI 为 6 万美元，单身，有一个孩子”
• “我该逐项扣除还是采用标准扣除？我支付了 1.5 万美元的房贷利息和 1.2 万美元的州税”
• “解释 Backdoor Roth IRA 策略”
• “一个年收入 3.5 万美元、由 4 人组成的家庭可获得多少 EITC？”
• “我今年行使了 ISO：需要缴纳 AMT 吗？”
• “帮我规划年末税务安排。我有 401k 和 HSA。”

替代方案：Docker

docker build -t irs-taxpayer-mcp .
docker run -i irs-taxpayer-mcp

替代方案：Streamable HTTP 传输

npx irs-taxpayer-mcp --http --port 3000
# MCP endpoint: http://127.0.0.1:3000/mcp
# Health check: http://127.0.0.1:3000/health

HTTP 模式为无状态模式，默认仅绑定到回环主机。浏览器请求必须使用完全匹配的允许来源。使用可重复的标志添加受信任的浏览器来源：

npx irs-taxpayer-mcp --http \
  --allowed-origin https://trusted-client.example

旧版 --sse 标志仍是 --http 的弃用别名。不会公开旧版 /sse 和 /messages 端点。

🛠️ 工具（44）

所有工具都使用当前的 MCP registerTool API。每个工具都声明了只读注解和输出架构，并同时返回人类可读文本和 structuredContent。错误结果包含稳定的错误代码、消息和恢复建议。

旗舰工作流 generate_tax_plan（1.0）会返回领域结构化结果、假设、官方来源出处、计算跟踪记录以及明确标注的不支持范围。确定性引擎不会发起网络请求、进行持久化或遥测。其结构化隐私元数据会报告使用的是 MCP 适配器还是直接 CLI 路径。不支持的纳税年度、州税配置以及必需的工作表事实信息会直接失败关闭。参见本地税务规划器 1.0 合约。

联邦税计算

工具	功能
calculate_federal_tax	完整的联邦税计算，包含税率档位明细、AMT、NIIT（3.8%）、额外 Medicare 税（0.9%）、QBI 扣除、自雇税、资本利得、CTC
get_tax_brackets	按申报身份和年份列出税率档位及标准扣除额
compare_filing_statuses	对同一收入下的 4 种申报身份进行并排比较
estimate_quarterly_tax	预估季度税款（1040-ES），并提供安全港指南
calculate_total_tax	一次调用即可合并计算联邦税和州税，并提供实得工资及月收入
calculate_w4_withholding	预估每次发薪的预扣税款，并逐步提供 W-4 表格填写建议

扣除项分析

工具	功能
list_deductions	浏览所有扣除项，包括资格规则、限额和表格
standard_vs_itemized	比较标准扣除和逐项扣除，以及按年份适用的 SALT 限额（2024 纳税年度为 $10K，2025 纳税年度为 $40K）

税收抵免

工具	功能
list_tax_credits	20 多项联邦抵免：CTC、EITC、AOTC、电动汽车、太阳能、储蓄者抵免等
check_credit_eligibility	根据您的收入、家庭情况和个人状况快速筛查资格
calculate_eitc	精确计算 EITC，涵盖 0–3 名子女的逐步增加、稳定和逐步减少阶段

退休与策略

工具	功能
get_retirement_accounts	IRA、Roth、401k、SEP、Solo 401k、HSA、529：限额、税务处理和建议
get_retirement_strategy	后门 Roth、超级后门 Roth、Roth 转换阶梯、税收亏损／收益收割

税务规划与情景分析

工具	功能说明
generate_tax_plan	以隐私为先的本地规划，提供结构化结果、假设、来源、追踪信息和明确的适用边界
get_tax_planning_tips	个性化年末优化建议：401k 缴款达到上限、HSA、Roth 转换、税损收割、慈善捐赠集中安排
compare_tax_years	对比 TY2024 与 TY2025，了解税级变化和 OBBB 对税务的影响
estimate_self_employment_tax	完整的 SE 税分解：Schedule C 利润、SE 税、QBI 扣除、季度缴款、SEP/Solo 401k 限额
analyze_mortgage_tax_benefit	分析房贷利息与房产税扣除，并采用对应年份的 SALT 上限
analyze_education_tax_benefits	对比 AOTC 与终身学习抵免，提供学生贷款扣除和 529 计划指南

州税

工具	功能说明
get_state_tax_info	全部 50 个州及 DC 的参考数据和说明
estimate_state_tax	估算受支持的州税情形；不支持的税级数据将安全拒绝处理
compare_state_taxes	仅在所有请求的计算均受支持时比较各州税务
list_no_income_tax_states	列出 9 个没有广泛适用的个人所得税的州

IRS 信息

工具	功能说明
get_tax_deadlines	按纳税年度列出 IRS 重要日期和截止日期
check_refund_status	介绍如何查询退款状态（仅提供指导：无法访问 IRS 账户）
get_irs_form_info	介绍 14 种常见 IRS 表格（1040、W-2、1099、附表等）

OBBB 法案（2025）工具

工具	功能说明
calculate_obbb_deductions	计算 OBBB 的全部 4 项新增扣除：小费、加班费、老年人奖金、汽车贷款利息
what_changed_between_tax_years	对比任意两个受支持的纳税年度：税级、扣除、抵免、SALT 和 OBBB 条款

完整报告与分析

工具	功能
generate_full_tax_report	估算报告：收入、扣除额、联邦税、FICA、支持的州税、实得收入和退税相关输入
process_1099_income	处理多份 1099 表格（NEC、INT、DIV、B、MISC），并按类别分析税务影响
get_personalized_tax_calendar	根据您的情况（自雇、延期申报、投资）提供个性化截止日期
analyze_paycheck	核验薪资预扣税是否准确、预测年度税额并建议调整 W-4
compare_mfj_vs_mfs	比较 MFJ 与 MFS 的税额差异，并列出所有 MFS 限制警告
simulate_tax_scenario	假设情景建模：收入变化、搬迁、Roth 转换、401k、申报身份
assess_audit_risk	对 IRS 审计风险评分，识别风险信号并提供降低风险的建议
get_tax_document_checklist	根据您的收入和人生事件提供个性化报税文件清单
optimize_capital_gains	投资批次分析：0% 税率档位的收益收割、税损收割、洗售警告
plan_retirement_withdrawals	最优提款顺序（Traditional/Roth/Taxable）、RMD 计算、Roth 转换
plan_multi_year_taxes	3-5 年税务预测，包含税率档位管理和年龄里程碑
analyze_relocation_taxes	深入分析州际搬迁税务，涵盖多年节税情况和 SALT 影响

指引与反馈

工具	功能
run_tax_health_check	报告工具覆盖范围和内置税务年度数据的时效性
lookup_tax_rule	搜索内置税务知识库
get_form_filing_guide	为支持的 IRS 表格提供分步指引
submit_feedback	生成预填的 GitHub issue 链接，不会传输税务数据

📊 覆盖的税务年度

TY2024

使用 IRS Revenue Procedure 2023-34 支持历史税务年度计算。标准扣除额为 $14,600（单身）/ $29,200（MFJ）。CTC 为 $2,000。SALT 上限为 $10,000。

TY2025

反映 2025 年 7 月 4 日签署的 OBBB：

• 标准扣除额：$15,750（单身）/ $31,500（MFJ）/ $23,625（HoH）
• Child Tax Credit：每名子女 $2,200（较 $2,000 提高）
• SALT 上限：AGI ≤ $500K 时为 $40,000（原为 $10,000）
• 新增扣除额：小费（$25K）、加班费（$12.5K）、老年人额外扣除（65 岁及以上 $6K）、汽车贷款利息（$10K）
• 401k 追加缴款：60-63 岁为 $11,250（SECURE 2.0）

TY2026

采用 IRS Revenue Procedure 2025-32 以及 SSA 2026 年缴款和福利基数：

• 标准扣除额：$16,100（单身）/ $32,200（MFJ）/ $24,150（HoH）
• Child Tax Credit：每名符合条件的子女 $2,200，其中最高 $1,700 可退还
• SALT 上限：MAGI 不超过 $505,000 时为 $40,400；MFS 为 $20,200 和 $252,500
• Social Security 工资基数：$184,500
• 已更新普通收入、资本利得、EITC 和 AMT 门槛

支持范围与边界

本项目是一个确定性估算与规划引擎，不是税务申报或报税软件。

• 联邦估算涵盖各工具提供的 TY2024 至 TY2026 建模输入。它并未实现 Form 1040 的所有行、附表、选择、限制、结转或受抚养人规则。
• 州参考信息涵盖全部 50 个州和 DC。数值估算需要精确的纳税年度配置：TY2024 支持 AK、CA、FL、NV、SD、TN、TX 和 WY；TY2025 和 TY2026 支持 AK、FL、NH、NV、SD、TN、TX 和 WY。California TY2024 支持单身和已婚税率档。其他州、纳税年度及申报身份组合会返回错误。
• 州税计算尚未建模非完整年度或非居民收入分配、所有地方税，也未分别设置户主（HoH）和已婚分别申报（MFS）的税率档。
• QBI、AMT、审计风险、退休、搬迁和多年期输出均为规划估算，并采用了文档中说明的简化处理。
• 退税预测仅取决于所选工具建模的输入和可退还抵免额。它不代表 IRS 对退税额的认定。
• 此服务不会生成税表、签署税表、传输 MeF 数据，也不会验证申报资格。

请参阅 ROADMAP.md，了解实现可用于报税的联邦税表引擎的后续工作。

🧮 计算引擎

功能	状态
联邦所得税（7 个税率档 × 4 种申报身份）	✅
长期资本利得（0%/15%/20%）	✅
资本损失净额计算、年度限额、结转	规划级
社会保障福利税	Publication 915 规划模型
退休分配及提前支取税	根据提供的 1099-R 信息进行规划级估算
自雇税（SS + Medicare）	✅
净投资所得税（3.8% NIIT）	✅
附加 Medicare 税（0.9%）	✅
替代性最低税（AMT）	按优惠税率和注明的优惠项目限额建模
QBI 扣除额（Section 199A）	根据工资、UBIA 和 SSTB 限额进行规划级估算
带逐步取消机制的儿童税收抵免	✅
AOTC 和终身学习抵免	Form 8863 规划模型
EITC TY2024/TY2025/TY2026 计算	✅
标准扣除额与分项扣除额对比	✅
按纳税年度设定的 SALT 限额（OBBB）	✅
州参考数据（50 个州 + DC）	✅
州税数值估算	仅支持指定组合
20 多项联邦抵免参考与筛查	✅
退休账户参考与规划	规划估算
W-4 预扣税计算器	规划估算

数值回归测试引用 IRS Revenue Procedures、IRC 条款和相关立法。参考和规划工具可能会概述计算引擎未完全体现的规则。

🏗️ 从源代码构建

需要 Node.js 20 或更高版本。

git clone https://github.com/dma9527/irs-taxpayer-mcp.git
cd irs-taxpayer-mcp
npm install
npm run build
npm start          # stdio mode
npm run dev        # development mode (tsx)

🐛 发现 Bug？

• 计算错误或数据不正确？ 提交问题：请注明工具名称、纳税年度、经过取整或合成的示例，以及预期结果。请勿发布纳税人个人身份信息（PII）。
• 规划工具使用场景或产品缺口？ 使用规划工具反馈表。请勿提供纳税人 PII 或真实税表。
• 有疑问或想参与讨论？ GitHub 讨论区
• 想要贡献？ 请参阅 CONTRIBUTING.md

🤝 参与贡献

欢迎贡献。请确保：

• 所有测试均通过（npm test）
• 构建成功（npm run build）
• TypeScript 中不使用 any 类型
• 数据变更附有 IRS 来源引用

完整指南请参阅 CONTRIBUTING.md。

📄 License

MIT