Nonprofit Explorer MCP Server

@cyanheads/nonprofit-explorer-mcp-server Search and explore 1.8M+ US nonprofits, fetch Form 990 financials, and access IRS filing history via MCP. STDIO or Streamable HTTP. 3 Tools

Public Hosted Server: https://nonprofit-explorer.caseyjhand.com/mcp

Overview

IRS Form 990 data for 1.8M+ tax-exempt organizations, via the ProPublica Nonprofit Explorer API. Search by name, fetch an org's financial snapshot, and pull its full filing history.

Tools

Capability reference

nonprofit_search_organizations tool

• Full-text query — supports quoted phrases ("Red Cross"), required terms (+evanston), excluded terms (-dental)
• Optional filters: state/territory name or postal code (including military codes and ZZ for foreign entities), NTEE major sector (1–10 or a case-insensitive major letter), and 501(c) subsection code (3 covers both public charities and private foundations — see foundation_type on nonprofit_get_organization to tell them apart). Names and letters normalize to the upstream codes shown in active_filters; unrecognized states are rejected before a request
• sub_name is the upstream legal name with an optional secondary line; it can repeat name or be null
• Paginated at 25 per page (page, zero-indexed); num_pages, per_page, and page_offset track position
• API caps total results at 10,000 — total_results === 10000 means the actual count may be higher, and a page whose offset reaches that ceiling is refused (pagination_ceiling)
• Zero matches and a page past the last one both succeed with an empty organizations array and a notice explaining which case it is
• Returns EINs — pass to nonprofit_get_organization or nonprofit_get_filings for details

nonprofit_get_organization tool

• Accepts EIN as integer (530196605) or string with or without hyphen ("53-0196605"); use nonprofit_search_organizations first if you only have an org name
• Returns legal identity, address, NTEE code, 501(c) type, and IRS ruling date
• IRS Business Master File standing: deductibility (including the deductible-by-treaty case), exemption status, and public-charity vs. private-foundation classification — each decoded from its IRS code with the raw code retained
• latest_filing is the latest extracted financial snapshot: revenue, expenses, assets, liabilities, net assets, and source PDF link. latest_return separately identifies the newest return across extracted and PDF-only histories; a newer return need not have extracted figures
• Filing requirements, private-foundation filing requirements, affiliation, and group exemption number come from the IRS Business Master File. Empty-history guidance uses these codes without claiming why a particular filing is absent
• filing_count counts filings with extracted data; filing_count_pdf_only separately counts PDFs without financial extracts. Use nonprofit_get_filings for those links; PDF-only histories have no financial snapshot
• Data lags 1–2 years — tax_prd_yr in the snapshot is the fiscal year of the filing, not the current year

nonprofit_get_filings tool

• All Form 990 filings with extracted data, sorted by full tax period newest first — per filing: revenue, expenses, assets, liabilities, net assets, revenue breakdown (contributions, program service, investment income), and the source PDF link
• Optional inclusive from_year / to_year bounds apply to both extracted and PDF-only histories. Totals remain unfiltered; an empty selected interval does not mean the organization has no history
• Financial fields follow each return's form type. For 990-PF, investment income is savings interest plus dividends and securities interest (Part I column (a), lines 3–4); both components must be extracted. It excludes capital gains, rents, and net investment income
• 990-PF filings include grants_paid, distributable_amount, fair_market_value_assets, and net_investment_income. The distributable amount is a payout requirement, not actual payments or a compliance measure
• program_expense_ratio is always null — ProPublica returns no Form 990 Part IX program-service expense total, so the program/management/fundraising split is only in the source PDF
• Form 990 includes other salaries and wages, payroll taxes, professional fundraising fees, and fundraising event gross, direct expenses, and net income. For 990-EZ, event gross is separate from combined gaming/fundraising expenses and net income; the combined figures cannot establish event-only results
• Executive compensation includes the source field for 990 and 990-PF. The 990-EZ extract has no compensation source: amount and field name are null, with guidance to Part IV of the PDF
• filings_pdf_only retains fiscal years and tax periods for returns without extracted data, including returns newer than the financial snapshots
• An EIN that resolves to a real org with no 990 on record returns an empty filings array plus a notice, not an error
• Data lags 1–2 years — always cite tax_prd_yr (fiscal year) when presenting figures

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

ProPublica Nonprofit Explorer / IRS-specific:

• Keyless access — ProPublica Nonprofit Explorer API requires no API key
• Covers 1.8M+ IRS-recognized tax-exempt organizations
• IRS Form 990 data: annual filings for public charities (990), small orgs (990-EZ), and private foundations (990-PF)
• Source filing PDF link on every filing record, except where IRS PDF processing lags the extracted data and pdf_url is still null
• Data sourced from ProPublica Nonprofit Explorer, derived from IRS Form 990 filings; data lags 1–2 years

Agent-friendly output:

• Provenance on every response — data_source attribution on all tool outputs, ProPublica URL for direct verification
• Filing-year clarity — tax_prd_yr prominently labeled as fiscal year with explicit lag caveat in every financial response
• Null values are rendered, not dropped — the formatted text names why a value is absent (never recorded by the IRS, not extracted from the filing, not carried by that form type), and structuredContent keeps an explicit null rather than omitting the key
• Field-name transparency on compensation — field_name and form_type exposed so agents know exactly which IRS field was read

The published nonprofit-explorer-guide covers diligence, financial comparisons, and when to inspect the source return. It is included in npm, Docker, and desktop bundles and served through MCP skill resources.

Getting started

Public Hosted Instance

A public instance is available at https://nonprofit-explorer.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP, with this client config:

{

"mcpServers": { "nonprofit-explorer-mcp-server": { "type": "streamable-http", "url": "https://nonprofit-explorer.caseyjhand.com/mcp" } } }

Self-Hosted / Local

Add the following to your MCP client configuration file.

{

"mcpServers": { "nonprofit-explorer-mcp-server": { "type": "stdio", "command": "bunx", "args": ["@cyanheads/nonprofit-explorer-mcp-server@latest"], "env": { "MCP_TRANSPORT_TYPE": "stdio", "MCP_LOG_LEVEL": "info" } } } }

Or with npx (no Bun required):

{

"mcpServers": { "nonprofit-explorer-mcp-server": { "type": "stdio", "command": "npx", "args": ["-y", "@cyanheads/nonprofit-explorer-mcp-server@latest"], "env": { "MCP_TRANSPORT_TYPE": "stdio", "MCP_LOG_LEVEL": "info" } } } }

Or with Docker:

{

"mcpServers": { "nonprofit-explorer-mcp-server": { "type": "stdio", "command": "docker", "args": [ "run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/nonprofit-explorer-mcp-server:latest" ] } } }

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http

Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.4.0 or higher (or Node.js v24+).
• No API key required — ProPublica Nonprofit Explorer is a keyless public API.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/nonprofit-explorer-mcp-server.git

1. Navigate into the directory:

cd nonprofit-explorer-mcp-server

1. Install dependencies:

bun install

1. Configure environment:

cp .env.example .env

edit .env as needed (no required vars — server works out of the box)

Configuration

All configuration is validated at startup. Key environment variables:

| `MCP_TRANSPORT_TYPE