Irs Taxpayer Mcp

---

⚠️ 免責事項：このツールは、教育および情報提供のみを目的として税額を見積もるものです。税務、法律、または財務に関する助言を提供するものではありません。必ず資格を持つ税務専門家にご相談ください。

法的通知：このソフトウェアは、いかなる種類の保証もなく「現状有姿」で提供されます。作者およびコントリビューターは、税務専門家、公認会計士（CPA）、登録税務代理人、または弁護士ではありません。このソフトウェアを使用しても、弁護士と依頼人、公認会計士と顧客、または受託者としての関係は成立しません。税法は頻繁に変更され、管轄区域によって異なります。計算に誤りや漏れが含まれる場合や、最新の法改正が反映されていない場合があります。税務申告に関する判断は、すべてご自身の責任で行ってください。作者は、このソフトウェアの使用から生じるいかなる損害についても責任を負いません。法的通知の全文はDISCLAIMER.mdをご覧ください。

この MCP が選ばれる理由

税務申告の時期は大変です。W-2、1099、控除、税額控除を整理し、項目別控除を申請するべきか、標準控除を利用するべきかを判断しなければなりません。「2025年のSALT控除の上限」を検索すると、食い違う記事が10件も見つかります。

このパッケージは、2つのインターフェースを備えた決定論的なローカル税務エンジンを提供します。ローカルの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 人」
• 「項目別控除と標準控除のどちらを選ぶべきですか？住宅ローン利息 1 万 5 千ドル、州税 1 万 2 千ドルを支払っています」
• 「バックドア 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 モードはステートレスで、デフォルトではループバックホストのみにバインドされます。ブラウザーからのリクエストでは、許可された Origin と完全に一致する必要があります。信頼できるブラウザー Origin を、繰り返し指定できるフラグで追加します。

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

従来の --sse フラグは、引き続き非推奨の --http エイリアスとして使用できます。旧 /sse および /messages エンドポイントは公開されません。

🛠️ ツール（44）

すべてのツールは、現行の MCP registerTool API を使用します。各ツールは読み取り専用のアノテーションと出力スキーマを提示し、人間が読めるテキストと structuredContent の両方を返します。エラー結果には、安定したエラーコード、メッセージ、復旧の提案が含まれます。

1.0 の主力機能である generate_tax_plan ワークフローは、ドメイン固有の構造化結果、前提条件、公式ソースの出典情報、計算トレース、明示的な未対応範囲を返します。決定論的エンジンは、ネットワークリクエスト、永続化、テレメトリーを一切行いません。構造化されたプライバシーメタデータには、MCP アダプターと直接 CLI パスのどちらを使用したかが報告されます。未対応の税年度、州のプロファイル、必須のワークシート情報がある場合は、安全側に倒して処理を拒否します。ローカル税務プランナー 1.0 の仕様を参照してください。

連邦税の計算

ツール	内容
calculate_federal_tax	税率区分ごとの内訳、AMT、NIIT（3.8%）、追加メディケア税（0.9%）、QBI控除、自営業税、キャピタルゲイン、CTCを含む連邦税の全額
get_tax_brackets	申告区分と年度別の税率区分および標準控除
compare_filing_statuses	同じ所得について、4つすべての申告区分を横並びで比較
estimate_quarterly_tax	セーフハーバーに関する案内を含む、四半期ごとの予定納税額（1040-ES）
calculate_total_tax	連邦税と州税を1回の呼び出しで合算し、手取り額と月収も算出
calculate_w4_withholding	W-4フォームに関する段階的な推奨事項を含む、給与支給ごとの源泉徴収額の見積もり

控除の分析

ツール	内容
list_deductions	適用条件、上限、フォームとともに、すべての控除を確認できます
standard_vs_itemized	年度別のSALT上限（TY2024は$10K、TY2025は$40K）を適用して、標準控除と項目別控除を比較します

税額控除

ツール	内容
list_tax_credits	20種類以上の連邦税額控除：CTC、EITC、AOTC、EV、太陽光、貯蓄者向け税額控除など
check_credit_eligibility	所得、家族構成、状況に基づく簡易的な適格性チェック
calculate_eitc	子ども0～3人を対象に、段階的な増額・定額・減額を含むEITCを正確に計算します

退職後の資産形成と税務戦略

ツール	内容
get_retirement_accounts	IRA、Roth、401k、SEP、Solo 401k、HSA、529の上限、税務上の取り扱い、ヒント
get_retirement_strategy	バックドア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とLifetime Learning Creditの比較、学生ローン控除、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	IRSの一般的な14種類のフォーム（1040、W-2、1099各種、Scheduleなど）の情報

OBBB法（2025年）ツール

ツール	機能
calculate_obbb_deductions	OBBBで新設された4つの控除（チップ、残業、高齢者向けボーナス、自動車ローン利息）をすべて計算します
what_changed_between_tax_years	対応する任意の2つの税年度を比較します：税率区分、控除、税額控除、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／課税対象）、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イシューへのリンクを生成します

📊 対応する税年度

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：対象となる子ども1人につき2,200ドル（2,000ドルから増額）
• SALTの上限額：AGIが500,000ドル以下の場合は40,000ドル（従来は10,000ドル）
• 新たな控除：チップ（25,000ドル）、時間外労働（12,500ドル）、高齢者ボーナス（65歳以上で6,000ドル）、自動車ローンの利息（10,000ドル）
• 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：対象となる子ども1人につき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)

🐛 バグを見つけましたか？

• 計算エラーまたはデータの誤りですか？ 課題を作成してください。ツール名、税務年度、丸めた値または合成した例、期待される結果を含めてください。納税者の個人識別情報（PII）は投稿しないでください。
• プランナーのユースケースまたは製品の不足点ですか？ プランナー向けフィードバックフォームを利用してください。納税者のPIIや実際の税務申告書は含めないでください。
• 質問や議論ですか？ GitHub Discussions
• 貢献をご希望ですか？ CONTRIBUTING.mdをご覧ください。

🤝 貢献

貢献を歓迎します。以下を確認してください。

• すべてのテストが成功すること（npm test）
• ビルドが成功すること（npm run build）
• TypeScriptでany型を使用していないこと
• データを変更する場合はIRSの出典を記載すること

詳しいガイドラインについては、CONTRIBUTING.mdをご覧ください。

📄 License

MIT