Skip to main content
Glama
soi-mcp
by mcpwright

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 as io.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 one refresh <year> away. See the roadmap for what's next.

Tools

Tool

What it does

lookup_zip(zip_code)

Confirm a ZIP has SOI data → state, number of returns, number of individuals, tax year. A good first call.

get_income(zip_code)

Adjusted gross income (AGI), average AGI per return, and income components: salaries/wages, taxable interest, ordinary dividends, business net income, net capital gain.

get_agi_distribution(zip_code)

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.

get_tax(zip_code)

Income tax, income tax before credits, total tax liability (broader — includes self-employment tax, etc.), total tax payments, and average total tax per return.

get_credits(zip_code)

EITC take-up (overall and split by number of qualifying children: none / one / two / three or more) and the additional (refundable) child tax credit.

get_deductions(zip_code)

Standard vs. itemized deductions (count and amount), the taxes-paid (SALT) deduction, and the percent of returns that itemized.

get_filing_status(zip_code)

Single / married-filing-jointly / head-of-household return counts, elderly returns (age 65+), and the count and share of electronically filed returns.

compare_zips(zips, metric)

Rank several ZIPs by one metric (e.g. avg_agi_per_return, pct_returns_200k_plus, total_tax_liability, eitc_amount), highest first.

get_state_totals(state)

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 "CA" or "California".

get_soi_field(zip_code, field)

Escape hatch: the raw value of one SOI field code (e.g. A00100 for AGI, N1 for returns) for a ZIP, summed across brackets, with its label and unit. Limited to the fields in the store.

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-soi

The 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 comparison

Claude Code

claude mcp add soi -- uvx mcpwright-soi

Claude 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-soi runs locally over stdio.

Storage: the dataset lives in a SQLite file under your OS cache dir (override with the SOI_MCP_STORE env var). Delete it any time; setup / refresh rebuilds 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 Inspector

Roadmap

  • lookup_zip / get_income / get_agi_distribution — the income backbone

  • get_tax / get_credits / get_deductions / get_filing_status — the tax side

  • compare_zips — rank ZIPs by a metric

  • get_state_totals — state rollups from the IRS 00000 row

  • get_soi_field — raw-field escape hatch

  • setup / refresh [year] — download once, re-pull or pick an older tax year

  • Publish 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 tools
compare_zipsCompare ZIPsA
Read-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 ZIPA
Read-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 ZIPA
Read-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 ZIPA
Read-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 ZIPA
Read-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 ZIPA
Read-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 fieldA
Read-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 totalsA
Read-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 ZIPA
Read-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 ZIPA
Read-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

    A4.4/5.0

    Scored across 10 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables location intelligence for US ZIP codes, allowing users to search, profile, and compare ZIP codes across various domains like crime, income, schools, and more.
      -
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI agents to access SEC EDGAR filings, US Treasury rates, BLS labor statistics, and economic indicators without API keys.
      6
      45 npm
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables LLM agents to query the Explore Local Statistics API for local area data like employment rates and demographics.
      -
    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      8
      37 PyPI
      MIT