irs-exempt-orgs
by pipeworx-io
README.md
# @pipeworx/irs-exempt-orgs
US tax-exempt organisations from the IRS Exempt Organizations Business Master File: ruling date (when the IRS determined exemption), foundation type, subsection, NTEE category and latest assets, income and revenue, for about 1.9 million organisations. Look one up by EIN, or find them by ruling date, foundation type, state and size.
Part of [Pipeworx](https://pipeworx.io) — an MCP gateway connecting AI agents to 2014+ live data sources. This is an independent, unofficial integration — not affiliated with, endorsed by, or published by the upstream provider.
## Tools
- `irs_exempt_org_get(ein)` — the full record for one EIN, with every code returned raw and decoded (subsection, foundation type, deductibility, exemption status, asset and income bands, NTEE major group).
- `irs_exempt_org_search(ruling_from?, ruling_to?, private_foundation?, foundation_code?, state?, subsection?, ntee?, min_assets?, sort?, limit?)` — finds organisations, ranked by latest assets (or income, revenue, ruling date). Answers "private foundations determined in 2025 or later, largest first".
```
irs_exempt_org_search({private_foundation: true, ruling_from: "2025-01", limit: 10})
-> organizations sorted by assets_usd, each with ruling_date, foundation {code, meaning}, ntee
irs_exempt_org_get({ein: "010548657"})
-> Kuehner Brothers Foundation Inc, ruling_date 2003-03, foundation 04 private non-operating
```
## Auth
Keyless.
## Data sources
- IRS, Exempt Organizations Business Master File Extract. US federal data, public domain. Every answer carries `data_as_of` (the date the IRS last published the extract; the file has no date of its own) and `answered_from` (always `stored_copy`).
The extract is about 340 MB, too big to read per call, so a stored copy answers every call and a scheduled loader refreshes it (the IRS republishes monthly). There is no live fallback: before the first load, or if the copy cannot be read, both tools return `found: false, reason: "stored_copy_unavailable"` rather than an empty result.
Caveats worth passing on:
- **Search must be bounded.** Give a ruling-date window, or `private_foundation: true`, or a small state. A search that would scan more than 150,000 organisations returns `reason: "too_broad"` and says how to narrow it. Searching by organisation name is not built; the lookup is by EIN.
- **A null amount is not zero.** An organisation that has not filed a return carries no asset or income figure; the file leaves it blank and so does the answer. Amounts are as last reported, which may be several years old (`latest_return_tax_period` on the full record).
- **Ruling date is the IRS determination, not the founding date.** An organisation can be decades older than its ruling.
- **Codes not in the pack's tables decode to null** with the raw code kept; nothing is guessed.
- **Organisation records only.** The file's "in care of" line, which is usually a person's name, and its secondary sort name are not loaded or returned.
- **Fields are positional in the stored shards** (see the header of `src/index.ts` and `scripts/lib/irs-eo-parse.mjs`); the test suite builds shards with the loader's own module and reads them through the pack.
## Quick Start
Add to your MCP client (Claude Desktop, Cursor, Windsurf, etc.):
```json
{
"mcpServers": {
"irs-exempt-orgs": {
"url": "https://gateway.pipeworx.io/irs-exempt-orgs/mcp"
}
}
}
```
### What this endpoint actually serves
`tools/list` at `https://gateway.pipeworx.io/irs-exempt-orgs/mcp` returns the tools in the table
above **plus the shared Pipeworx meta-tools** — `ask_pipeworx`,
`discover_tools`, `search_within`, `remember`/`recall` and the rest of the
gateway-wide set. So the tool count you see is larger than this table: a
single-pack endpoint currently lists roughly 30 shared tools alongside the
pack's own. The connection's `initialize` response states its exact scope, and
is the authoritative answer for a given day.
This is deliberate, not multiplexing by accident. The meta-tools are what let a
scoped connection answer a question this pack does not cover — via
`ask_pipeworx`, which routes across the whole catalog — without you adding a
second MCP server. There is currently no way to mount a pack endpoint without
them; if the extra schemas cost you more context than the routing is worth,
connect to the full gateway once rather than to several pack endpoints.
Or connect to the full Pipeworx gateway to get every pack's tools listed
directly, instead of just this one's:
```json
{
"mcpServers": {
"pipeworx": {
"url": "https://gateway.pipeworx.io/mcp"
}
}
}
```
Both URLs reach the same gateway and the same 2014+ data sources. The
only difference is which pack's tools are listed **directly**; `ask_pipeworx`
reaches all of them from either one.
## No MCP client? Call it over HTTP
```bash
curl -X POST https://gateway.pipeworx.io/v1/tools/irs_exempt_org_get \
-H 'Content-Type: application/json' \
-d '{"ein":"010548657"}'
```
No account needed for the first calls. Inspect any tool: `GET https://gateway.pipeworx.io/v1/tools/irs_exempt_org_get`. Find one: `POST https://gateway.pipeworx.io/v1/tools/search_packs` with `{"query":"..."}`.
## Run it from npm
`@pipeworx/mcp-irs-exempt-orgs` is a local stdio bridge to the Pipeworx gateway: your MCP client
starts it with `npx`, and it forwards every call to the same
`https://gateway.pipeworx.io/irs-exempt-orgs/mcp` endpoint shown above. It needs network access;
there is no offline mode.
```json
{
"mcpServers": {
"irs-exempt-orgs": {
"command": "npx",
"args": ["-y", "@pipeworx/mcp-irs-exempt-orgs"]
}
}
}
```
Without a key it calls anonymously, capped at 50 calls a day. A free account
raises that to 200 a day: get a key at https://pipeworx.io/signup and add
`"env": { "PIPEWORX_API_KEY": "<your key>" }` to the server entry.
The key is sent as a Bearer token, the same way a hosted connection sends it,
so calls are metered and billed exactly as they are there.
It lists **only** this pack's tools by default. Set `PIPEWORX_META_TOOLS=1` to
also list `ask_pipeworx` and the other gateway-wide tools.
Behind an HTTPS proxy: Node's built-in `fetch` does not read `HTTPS_PROXY` by
default. Newer Node releases honour it when `NODE_USE_ENV_PROXY=1` is set; check
your Node version's documentation.
## Using with ask_pipeworx
Instead of calling tools directly, you can ask questions in plain English —
this works on the pack endpoint above as well as on the full gateway:
```
ask_pipeworx({ question: "your question about Irs Exempt Orgs data" })
```
The gateway picks the right tool and fills the arguments automatically.
## More
- [Docs and guides](https://pipeworx.io/docs)
- [pipeworx.io](https://pipeworx.io)
## License
MIT