soi-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@soi-mcp What is the income distribution for ZIP 90210?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
soi-mcp
IRS income & tax statistics by ZIP code, inside your agent. An MCP
server that lets an LLM pull the income distribution, tax, credits, and deductions of any U.S. ZIP
straight from the IRS Statistics of Income (SOI) — built on Anthropic's official
mcp Python SDK.
All tools are read-only and the data is public domain (a U.S. government work) — no API key required. The dataset is downloaded once into a local SQLite store and served offline.
Status: published —
uvx mcpwright-soi(PyPI) and listed in the official MCP Registry asio.github.mcpwright/soi-mcp. 10 tools, working today (see below). The IRS SOI ZIP release lags ~2–3 years; the latest available year (currently Tax Year 2022) loads by default, and older years are onerefresh <year>away. See the roadmap for what's next.
Tools
Tool | What it does |
| Confirm a ZIP has SOI data → state, number of returns, number of individuals, tax year. A good first call. |
| Adjusted gross income (AGI), average AGI per return, and income components: salaries/wages, taxable interest, ordinary dividends, business net income, net capital gain. |
| The distinctive one. The ZIP's returns and AGI split across the six IRS AGI brackets (<$25k, $25–50k, $50–75k, $75–100k, $100–200k, $200k+), with each bracket's share — the income shape of a ZIP, not just an average. |
| Income tax, income tax before credits, total tax liability (broader — includes self-employment tax, etc.), total tax payments, and average total tax per return. |
| EITC take-up (overall and split by number of qualifying children: none / one / two / three or more) and the additional (refundable) child tax credit. |
| Standard vs. itemized deductions (count and amount), the taxes-paid (SALT) deduction, and the percent of returns that itemized. |
| Single / married-filing-jointly / head-of-household return counts, elderly returns (age 65+), and the count and share of electronically filed returns. |
| Rank several ZIPs by one metric (e.g. |
| A whole state's totals and AGI-bracket mix (returns, individuals, AGI, average AGI per return, income tax, total tax liability), from the IRS state rollup. Accepts |
| Escape hatch: the raw value of one SOI field code (e.g. |
All dollar amounts are returned in whole USD (the source reports thousands). Counts are numbers of returns, rounded by the IRS to the nearest 10.
Related MCP server: publicfinance
Install
Requires Python 3.12+. The zero-clone way to run it (the PyPI package is mcpwright-soi; the
command, server, and tools are all "soi"):
uvx mcpwright-soiThe first tool call downloads the latest SOI ZIP file (~200 MB) into a local SQLite store under your OS cache directory and serves everything offline thereafter. To pre-load (or to pick a specific tax year) without waiting for the first query:
uvx mcpwright-soi setup # download the latest available year
uvx mcpwright-soi refresh 2021 # re-pull a specific older year for comparisonClaude Code
claude mcp add soi -- uvx mcpwright-soiClaude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"soi": { "command": "uvx", "args": ["mcpwright-soi"] }
}
}OpenAI Agents SDK (Python)
It's a standard MCP server, so it works with any MCP-capable client — not just Claude. With the 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)Any other MCP client (Cursor, VS Code, Cline, Goose, Zed, …)
They all launch a stdio MCP server the same way — point yours at:
{
"mcpServers": {
"soi": { "command": "uvx", "args": ["mcpwright-soi"] }
}
}Hosted chat connectors (e.g. ChatGPT connectors) expect a remote MCP server over Streamable HTTP;
mcpwright-soiruns locally over stdio.
Storage: the dataset lives in a SQLite file under your OS cache dir (override with the
SOI_MCP_STOREenv var). Delete it any time;setup/refreshrebuilds it.
A note on suppression: the IRS excludes ZIPs with fewer than 100 returns (folding them into a "99999" bucket) and suppresses line items with fewer than 20 returns. Summed ZIP totals can therefore slightly understate reality and won't exactly equal the state total. All figures are aggregates of filed returns, not a population census.
Develop
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 InspectorRoadmap
lookup_zip/get_income/get_agi_distribution— the income backboneget_tax/get_credits/get_deductions/get_filing_status— the tax sidecompare_zips— rank ZIPs by a metricget_state_totals— state rollups from the IRS 00000 rowget_soi_field— raw-field escape hatchsetup/refresh [year]— download once, re-pull or pick an older tax yearPublish to PyPI (
mcpwright-soi) + the official MCP Registry (io.github.mcpwright/soi-mcp)Multi-year queries in one call (trend a ZIP across tax years)
Privacy
soi-mcp runs entirely on your machine. It collects, stores, or transmits no personal data
— no accounts, no tracking, no telemetry. Its only outbound requests go to the U.S. IRS static
file host (www.irs.gov/pub/irs-soi) to download the public SOI ZIP-code CSV; no API key is
needed and nothing about your queries leaves your machine. The downloaded dataset is cached on
disk as a local SQLite file (under your OS cache dir, or SOI_MCP_STORE); delete it any time.
Full policy: https://mcpwright.com/privacy/
Questions & feedback
Questions, ideas, or "could it do X?" → Discussions
Bugs & concrete feature requests → Issues
Contributions welcome — and if you build something with it, I'd love to hear about it.
Part of mcpwright · built by Devender Gollapally
Available Tools
10 toolscompare_zipsCompare ZIPsARead-only
Rank several ZIPs by a single metric, highest value first.
`zips`: a list of 5-digit US ZIPs to compare. `metric`: one of
`total_returns`, `adjusted_gross_income`, `avg_agi_per_return`,
`pct_returns_200k_plus`, `total_income`, `salaries_and_wages`, `income_tax`,
`total_tax_liability`, `avg_total_tax_per_return`, `eitc_amount`. Returns each
ZIP's value, sorted descending; ZIPs with no SOI data are listed last. A 0
for a sparse metric (e.g. `eitc_amount`) may be IRS-suppressed, not a true
zero.
Inputs: zips (required), metric (required). Returns: Several ZIPs ranked by one metric, highest value first.
get_agi_distributionGet AGI distribution by ZIPARead-only
The income distribution of a ZIP across the six IRS AGI brackets.
`zip_code`: a 5-digit US ZIP. Returns, for each bracket (<$25k, $25-50k,
$50-75k, $75-100k, $100-200k, $200k+), the number of returns and total AGI
plus each bracket's share of the ZIP's returns and AGI. This is the income
*shape* of a ZIP — what a single median can't show.
Note: a bracket showing 0 may be IRS-suppressed (<20 returns in that cell)
rather than truly empty, so the other brackets' shares can be slightly
overstated.
Inputs: zip_code (required). Returns: The income distribution of a ZIP across the six AGI brackets.
get_creditsGet credits by ZIPARead-only
Refundable-credit take-up for a ZIP: the EITC and additional child tax credit.
`zip_code`: a 5-digit US ZIP. Returns the number of returns and total amount
for the Earned Income Tax Credit (overall and split by number of qualifying
children: none / one / two / three or more), plus the additional (refundable)
child tax credit. Amounts in USD.
Note: a 0 may be IRS-suppressed (<20 returns in each AGI-bracket cell)
rather than a true zero — it does not prove no one claims the credit.
Inputs: zip_code (required). Returns: Refundable-credit take-up for a ZIP (EITC and the additional CTC).
get_deductionsGet deductions by ZIPARead-only
Deduction measures for a ZIP: standard vs. itemized, plus SALT.
`zip_code`: a 5-digit US ZIP. Returns the count and amount of standard
deductions and itemized deductions, the taxes-paid (SALT) deduction, and the
percent of returns that itemized. Amounts in USD.
Note: a 0 may be IRS-suppressed (<20 returns in each AGI-bracket cell)
rather than a true zero — it does not prove no one in the ZIP itemizes.
Inputs: zip_code (required). Returns: Deduction measures for a ZIP (all dollar amounts in USD).
get_filing_statusGet filing status by ZIPARead-only
Filing-status mix for a ZIP: single / married-joint / head-of-household.
`zip_code`: a 5-digit US ZIP. Returns the number of single, married-filing-
jointly, and head-of-household returns, the number of elderly returns (age
65+), and the count and share of electronically filed returns.
Note: a 0 count may be IRS-suppressed (<20 returns in each AGI-bracket
cell) rather than truly absent.
Inputs: zip_code (required). Returns: Filing-status and filing-characteristic counts for a ZIP.
get_incomeGet income by ZIPARead-only
Income measures for a ZIP: AGI, average AGI per return, and components.
`zip_code`: a 5-digit US ZIP. Returns total adjusted gross income (AGI),
average AGI per return, and the main income components — salaries and wages,
taxable interest, ordinary dividends, business net income, and net capital
gain. All dollar amounts in USD.
Note: figures cover filed tax returns only. Average AGI is a *mean per
return*, not a median per household, and AGI omits most nontaxable income —
so it is not directly comparable to Census median household income.
Inputs: zip_code (required). Returns: Income measures for a ZIP (all dollar amounts in USD).
get_soi_fieldGet a raw SOI fieldARead-only
Raw value of a single SOI field for a ZIP — an escape hatch.
`zip_code`: a 5-digit US ZIP. `field`: a SOI field code (e.g. `A00100` for
AGI, `N1` for number of returns); case-insensitive. Returns that field summed
across the ZIP's AGI brackets, with its label and unit (USD for amount fields,
count for return counts). Limited to the fields held in the local store (the
same ones the other tools draw on); an unknown field errors with the list.
Note: a 0 may be IRS-suppressed (<20 returns in a cell) rather than a true
zero, and a sum over suppressed cells slightly understates the real total.
Inputs: field (required), zip_code (required). Returns: The value of a single SOI field for a ZIP, summed across AGI brackets.
get_state_totalsGet state totalsARead-only
State-level SOI totals and AGI distribution from the IRS state rollup.
`state`: a 2-letter USPS code (e.g. 'CA') or full state name (e.g.
'California'). Returns the state's total returns, individuals, AGI, average
AGI per return, income tax, total tax liability, and the income distribution
across the six AGI brackets. Drawn from the IRS 00000 state-total row.
Inputs: state (required). Returns: State-level totals from the SOI 00000 rollup row (all dollar amounts USD).
get_taxGet tax by ZIPARead-only
Tax measures for a ZIP: income tax, total liability, and average per return.
`zip_code`: a 5-digit US ZIP. Returns income tax, income tax before credits,
total tax liability (broader — includes self-employment tax and other taxes),
total tax payments, and the average total tax per return. Amounts in USD.
Inputs: zip_code (required). Returns: Tax measures for a ZIP (all dollar amounts in USD).
lookup_zipLook up a ZIPARead-only
Confirm a ZIP has SOI data and return its return and individual counts.
`zip_code`: a 5-digit US ZIP. A good first call to validate a ZIP before
asking for more detail. Returns the state, number of returns, number of
individuals, and the SOI tax year. ZIPs with <100 returns are excluded.
Inputs: zip_code (required). Returns: Basic SOI identity and size for a ZIP.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool targets a distinct facet of SOI data: validation, income, distribution, tax, credits, deductions, filing status, comparison, state aggregates, and raw field access. No two tools overlap in purpose, making selection unambiguous.
All tool names follow a clear verb_noun pattern with lowercase and underscores: lookup_zip, get_income, get_agi_distribution, compare_zips, etc. The variation in verbs (lookup, get, compare) is natural and consistent with each tool's action.
With 10 tools, the set is well-scoped for a domain-specific SOI server. Each tool covers a major data category, and the count fits comfortably within the ideal 3-15 range without redundancy or bloat.
The surface covers the full range of SOI data categories: counts, income, tax, credits, deductions, filing status, comparison, state-level totals, and a raw field escape hatch. There are no obvious dead ends or missing lifecycle operations for the stated purpose.
Maintenance
Related MCP Connectors
US ZIP code intelligence: demographics, weather, tax, crime, housing, voting, and more.
Stock, ETF, crypto, forex, economic and US housing market data by ZIP code for AI assistants.
Ziplore: US ZIP to county, FIPS, time zone, Census demographics; radius and city ZIPs. Free, no key.
Ziplore: US ZIP to county, FIPS, time zone, Census demographics; radius and city ZIPs. Free, no key.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceEnables location intelligence for US ZIP codes, allowing users to search, profile, and compare ZIP codes across various domains like crime, income, schools, and more.-
- AlicenseAqualityDmaintenanceEnables AI agents to access SEC EDGAR filings, US Treasury rates, BLS labor statistics, and economic indicators without API keys.645 npmMIT

ELS MCP serverofficial
FlicenseNot gradedqualityBmaintenanceEnables LLM agents to query the Explore Local Statistics API for local area data like employment rates and demographics.-- AlicenseAqualityCmaintenanceEnables looking up U.S. Census data by ZIP code, including income, demographics, housing, and education statistics, using a locally stored dataset from the American Community Survey.837 PyPIMIT