IRS SOI (income by ZIP)

soi-mcp

在你的 Agent 中查询按 ZIP 代码划分的 IRS 收入与税务统计数据。 一个 MCP 服务，让大模型直接从 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）、每份报税表的平均 AGI，以及收入构成：工资、应税利息、普通股息、营业净收入、净资本利得。
get_agi_distribution(zip_code)	本工具的特色功能。 ZIP 代码对应的报税表数量和 AGI 按 IRS 的六个 AGI 档位划分（<$25k、$25–50k、$50–75k、$75–100k、$100–200k、$200k+），并显示各档位占比——呈现 ZIP 代码对应的收入分布形态，而非仅提供平均值。
get_tax(zip_code)	所得税、抵免前所得税、总纳税义务（范围更广，包含自雇税等）、税款总额，以及每份报税表的平均总税款。
get_credits(zip_code)	EITC 申领情况（总体数据及按符合条件的子女数量划分：无、一名、两名、三名或以上）和额外儿童税收抵免（可退还部分）。
get_deductions(zip_code)	标准扣除与分项扣除（数量和金额）、已缴税款（SALT）扣除，以及采用分项扣除的报税表占比。
get_filing_status(zip_code)	单身、夫妻联合申报、户主申报的报税表数量；老年人报税表数量（65 岁及以上）；以及电子申报的报税表数量和占比。
compare_zips(zips, metric)	按一项指标对多个 ZIP 代码排序（例如 avg_agi_per_return、pct_returns_200k_plus、total_tax_liability、eitc_amount），按从高到低排列。
get_state_totals(state)	根据 IRS 州级汇总数据，提供整个州的总量和 AGI 档位分布（报税表数量、个人数量、AGI、每份报税表的平均 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）下载到操作系统缓存目录下的本地 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 服务，因此适用于所有支持 MCP 的客户端，而不只是 Claude。 使用 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 运行。

**存储：**数据集位于操作系统缓存目录下的 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）
• 在一次调用中查询多年数据（追踪某个 ZIP 代码在多个纳税年度的趋势）

隐私

soi-mcp 完全在你的机器上运行。它不会收集、存储或传输任何个人数据——不需要账户，不进行追踪，也没有遥测。它唯一的外部请求是向美国 IRS 静态文件主机（www.irs.gov/pub/irs-soi）下载公开的 SOI ZIP 代码 CSV；无需 API 密钥，你的查询内容也不会离开你的机器。下载的数据集会作为本地 SQLite 文件缓存在磁盘上（位于操作系统缓存目录下，或由 SOI_MCP_STORE 指定）；可随时删除。

完整政策：https://mcpwright.com/privacy/

问题与反馈

• 问题、想法，或“能不能实现 X？” → 讨论
• 错误与具体的功能请求 → 问题

欢迎贡献——如果你用它构建了什么，我也很乐意听听。

---

属于 mcpwright · 由 Devender Gollapally 构建