IRS SOI (income by ZIP)

soi-mcp

エージェント内で、ZIP コード別の IRS 所得・税統計を確認できます。 MCP サーバーです。LLM が IRS の統計所得（SOI）から、米国の任意の ZIP コードの所得分布、税額、税額控除、控除額を直接取得できます。Anthropic 公式の mcp Python SDK を基盤に構築されています。

すべてのツールは読み取り専用で、データはパブリックドメイン（米国政府の著作物）です。API キーは不要です。 データセットは一度ローカルの SQLite ストアにダウンロードされ、その後はオフラインで提供されます。

ステータス：公開済み — uvx mcpwright-soi（PyPI）で利用でき、公式 MCP Registry には io.github.mcpwright/soi-mcp として登録されています。現在、10 個のツールが利用できます（下記参照）。IRS SOI の ZIP データは公開までに約 2〜3 年の遅れがあります。既定では、現在利用可能な最新年（現在は税年度 2022 年）が読み込まれます。それ以前の年度も refresh <year> で取得できます。今後の予定についてはロードマップをご覧ください。

ツール

ツール	機能
lookup_zip(zip_code)	ZIP コードに SOI データがあることを確認し、州、申告件数、個人数、税年度を返します。最初に呼び出すのに適したツールです。
get_income(zip_code)	調整後総所得（AGI）、申告 1 件あたりの平均 AGI、および給与・賃金、課税対象利子、普通配当、事業純所得、純キャピタルゲインなどの所得項目を返します。
get_agi_distribution(zip_code)	このツールの特長です。 ZIP コード内の申告件数と AGI を IRS の 6 つの AGI 区分（<25k、25〜50k、50〜75k、75〜100k、100〜200k、200k 以上）に分け、各区分の割合も返します。平均値だけでなく、ZIP コードの所得の分布形状がわかります。
get_tax(zip_code)	所得税、税額控除前の所得税、税負担総額（自営業税などを含む、より広い範囲の税額）、納税総額、申告 1 件あたりの平均納税総額を返します。
get_credits(zip_code)	EITC の利用状況（全体、および適格児童数別：なし／1 人／2 人／3 人以上）と、追加児童税額控除（還付可能分）を返します。
get_deductions(zip_code)	標準控除と項目別控除（件数と金額）、納付税額控除（SALT）、項目別控除を申告した件数の割合を返します。
get_filing_status(zip_code)	単身／夫婦合算申告／世帯主の申告件数、高齢者（65 歳以上）の申告件数、電子申告された件数と割合を返します。
compare_zips(zips, metric)	複数の ZIP コードを 1 つの指標（例：avg_agi_per_return、pct_returns_200k_plus、total_tax_liability、eitc_amount）で比較し、高い順に並べます。
get_state_totals(state)	IRS の州別集計から、州全体の合計値と AGI 区分の内訳（申告件数、個人数、AGI、申告 1 件あたりの平均 AGI、所得税、税負担総額）を返します。"CA" または "California" を指定できます。
get_soi_field(zip_code, field)	必要に応じて、ZIP コードの SOI フィールドコード（例：AGI の A00100、申告件数の N1）の生の値を、区分ごとに合算して、ラベルと単位とともに返します。ストア内のフィールドのみが対象です。

金額はすべて米ドルの整数で返されます（元データは千ドル単位です）。件数は申告件数で、IRS により 10 件単位に四捨五入されています。

インストール

Python 3.12 以降が必要です。クローンせずに実行する方法（PyPI パッケージ名は mcpwright-soi で、コマンド、サーバー、ツールはいずれも「soi」です）：

uvx mcpwright-soi

最初のツール呼び出し時に、最新の SOI ZIP ファイル（約 200 MB）が OS のキャッシュディレクトリ内のローカル SQLite ストアにダウンロードされます。それ以降はすべてオフラインで利用できます。最初のクエリを待たずに、事前にデータを読み込む（または特定の税年度を指定する）には：

uvx mcpwright-soi setup            # download the latest available year
uvx mcpwright-soi refresh 2021     # re-pull a specific older year for comparison

Claude Code

claude mcp add soi -- uvx mcpwright-soi

Claude Desktop

claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "soi": { "command": "uvx", "args": ["mcpwright-soi"] }
  }
}

OpenAI Agents SDK（Python）

標準的な MCP サーバーなので、Claude だけでなく、MCP 対応のあらゆるクライアントで動作します。 OpenAI Agents SDK では、次のように使用できます：

from agents import Agent, Runner
from agents.mcp import MCPServerStdio

async def main():
    async with MCPServerStdio(
        name="soi",
        params={"command": "uvx", "args": ["mcpwright-soi"]},
    ) as soi:
        agent = Agent(
            name="Analyst",
            instructions="Use the SOI tools for IRS income and tax data by ZIP.",
            mcp_servers=[soi],
        )
        result = await Runner.run(
            agent, "What's the income distribution of ZIP 90210 vs 10001?"
        )
        print(result.final_output)

その他の MCP クライアント（Cursor、VS Code、Cline、Goose、Zed、…）

どのクライアントも同じ方法で stdio MCP サーバーを起動します。次のパスを指定してください。

{
  "mcpServers": {
    "soi": { "command": "uvx", "args": ["mcpwright-soi"] }
  }
}

ホスト型チャットコネクター（ChatGPT のコネクターなど）は、Streamable HTTP 経由のリモート MCP サーバーを必要とします。 mcpwright-soi はローカルで stdio 経由で実行されます。

ストレージ： データセットは OS のキャッシュディレクトリ内の SQLite ファイルに保存されます（SOI_MCP_STORE 環境変数で変更できます）。いつでも削除できます。setup / refresh で再構築されます。

抑制に関する注意： IRS は申告件数が 100 件未満の ZIP を除外し（「99999」バケットにまとめます）、申告件数が 20 件未満の項目を抑制します。そのため、ZIP の合計値は実際よりわずかに低くなる場合があり、州の合計値と正確には一致しません。すべての数値は提出された申告の集計値であり、人口の国勢調査ではありません。

開発

git clone https://github.com/mcpwright/soi-mcp && cd soi-mcp
uv sync
uv run pytest                                          # tests (mocked download + seeded SQLite)
uv run ruff check src/ && uv run ruff format --check src/   # lint + format
uv run mypy                                            # strict type checking
uv run mcp dev src/soi_mcp/server.py                   # poke the tools in the MCP Inspector

ロードマップ

• lookup_zip / get_income / get_agi_distribution — 所得の基盤
• get_tax / get_credits / get_deductions / get_filing_status — 税務関連
• compare_zips — 指標で ZIP を順位付け
• get_state_totals — IRS の 00000 行から州別集計を取得
• get_soi_field — 生フィールドにアクセスするための手段
• setup / refresh [year] — 一度ダウンロードし、再取得、または以前の課税年度を選択
• PyPI（mcpwright-soi）および公式 MCP Registry（io.github.mcpwright/soi-mcp）に公開
• 1 回の呼び出しで複数年を照会（課税年度をまたいだ ZIP の推移を取得）

プライバシー

soi-mcp はすべてお使いのマシン上で実行されます。個人データを収集、保存、送信することはありません。アカウント、トラッキング、テレメトリーもありません。外部へのリクエストは、公開されている SOI の ZIP コード CSV をダウンロードするために米国 IRS の静的ファイルホスト（www.irs.gov/pub/irs-soi）に送るものだけです。API キーは不要で、クエリに関する情報がお使いのマシンの外部に送信されることもありません。ダウンロードしたデータセットはローカルの SQLite ファイルとしてディスク上にキャッシュされます（OS のキャッシュディレクトリ内、または SOI_MCP_STORE の指定先）。いつでも削除できます。

ポリシー全文：https://mcpwright.com/privacy/

質問とフィードバック

• 質問、アイデア、「X もできますか？」 → ディスカッション
• バグと具体的な機能リクエスト → イシュー

コントリビューションを歓迎します。このツールを使って何かを作ったら、ぜひお知らせください。

---

mcpwright の一部 · Devender Gollapally が作成