nonprofit-explorer-mcp-server

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['ein'], 'properties': {'ein': {'anyOf': [{'type': 'integer', 'maximum': 9007199254740991, 'description': 'EIN as integer (e.g., 530196605). Leading zeros are stripped â\x80\x94 treat EIN as an integer key.', 'exclusiveMinimum': 0}, {'type': 'string', 'pattern': '^\\d{2}-?\\d{7}$', 'description': 'EIN as string, with or without hyphen (e.g., "53-0196605" or "530196605").'}], 'description': 'Employer Identification Number. Use nonprofit_search to resolve an org name to its EIN.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['ein', 'name', 'filings', 'filings_pdf_only', 'total_filings_with_data', 'total_filings_pdf_only', 'data_source', 'propublica_url']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'ein': {'type': 'number', 'description': 'Employer Identification Number as integer.'}, 'name': {'type': 'string', 'description': 'Legal org name per IRS.'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['not_found', 'upstream_error'], 'description': 'Machine-readable failure mode. Declared by this tool: `not_found`: The EIN does not correspond to a known organization in the Nonprofit Explorer database. `upstream_error`: ProPublica API returns a non-JSON body or network error. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'notice': {'type': 'string', 'description': 'Present when the organization resolved but Nonprofit Explorer holds no filing of any kind for it â\x80\x94 names the org and why the filing history is empty. An empty filings array without this notice means the org has filings that carry a PDF but no extracted data; read filings_pdf_only.'}, 'filings': {'type': 'array', 'items': {'type': 'object', 'required': ['tax_prd_yr', 'tax_prd', 'form_type', 'pdf_url', 'updated', 'total_revenue', 'total_expenses', 'total_assets', 'total_liabilities', 'net_assets', 'contributions_and_grants', 'program_service_revenue', 'investment_income', 'program_expense_ratio', 'executive_compensation'], 'properties': {'pdf_url': {'type': ['string', 'null'], 'description': 'Source Form 990 PDF link. Null for some IRS processing batches â\x80\x94 check filings_pdf_only.'}, 'tax_prd': {'type': 'number', 'description': 'YYYYMM month the fiscal year ended (e.g., 202306 = June 2023 fiscal year end).'}, 'updated': {'type': ['string', 'null'], 'description': 'ISO datetime ProPublica last updated this record. Null when not provided.'}, 'form_type': {'enum': ['990', '990-EZ', '990-PF'], 'type': 'string', 'description': 'IRS form type filed.'}, 'net_assets': {'type': ['number', 'null'], 'description': 'Net assets/fund balances (end of year) in USD. From totnetassetend. Null when not extracted.'}, 'tax_prd_yr': {'type': 'number', 'description': 'Fiscal year of this filing (e.g., 2023). NOT the filing date â\x80\x94 data lags 1â\x80\x932 years. Always cite.'}, 'total_assets': {'type': ['number', 'null'], 'description': 'Total assets (end of year) in USD. Null when not extracted.'}, 'total_revenue': {'type': ['number', 'null'], 'description': 'Total revenue in USD. Null when not extracted.'}, 'total_expenses': {'type': ['number', 'null'], 'description': 'Total expenses in USD. Null when not extracted.'}, 'investment_income': {'type': ['number', 'null'], 'description': 'Investment income (invstmntinc). 990/990-EZ only; null for 990-PF.'}, 'total_liabilities': {'type': ['number', 'null'], 'description': 'Total liabilities (end of year) in USD. Null when not extracted.'}, 'program_expense_ratio': {'anyOf': [{'type': 'object', 'required': ['ratio', 'program_expenses', 'total_expenses', 'management_compensation', 'other_salaries', 'fundraising_expenses', 'note'], 'properties': {'note': {'type': 'string', 'description': 'Methodology note naming the source of the functional allocation.'}, 'ratio': {'type': ['number', 'null'], 'description': 'Program-service expenses divided by total functional expenses, as a decimal 0.0â\x80\x931.0. Always null against the current data source, which reports no program-service expense total.'}, 'other_salaries': {'type': ['number', 'null'], 'description': 'Other salaries and wages (othrsalwages) in USD. Null when not reported.'}, 'total_expenses': {'type': ['number', 'null'], 'description': 'Total functional expenses in USD â\x80\x94 Form 990 Part IX column (A). From totfuncexpns.'}, 'program_expenses': {'type': ['number', 'null'], 'description': 'Program-service expenses in USD â\x80\x94 Form 990 Part IX column (B), line 25.'}, 'fundraising_expenses': {'type': ['number', 'null'], 'description': 'Professional fundraising fees (profndraising) in USD. Null when not reported.'}, 'management_compensation': {'type': ['number', 'null'], 'description': 'Officer/director/trustee compensation (compnsatncurrofcr) in USD. Null when not reported.'}}, 'additionalProperties': False}, {'type': 'null'}], 'description': 'Always null against the current data source. ProPublica returns no Form 990 Part IX column (B) program-service expense total, and the functional allocation across program, management, and fundraising cannot be reconstructed from the fields it does return. Read Part IX of the filing at pdf_url for the split.'}, 'executive_compensation': {'type': 'object', 'required': ['amount', 'field_name', 'form_type', 'note'], 'properties': {'note': {'type': 'string', 'description': 'Plain-English description of what this field covers and where to find per-officer detail.'}, 'amount': {'type': ['number', 'null'], 'description': 'Total executive compensation in USD. Null when not reported.'}, 'form_type': {'enum': ['990', '990-EZ', '990-PF'], 'type': 'string', 'description': 'Form type this compensation field is sourced from.'}, 'field_name': {'enum': ['compnsatncurrofcr', 'compofficers'], 'type': 'string', 'description': 'Source API field the amount was read from â\x80\x94 compnsatncurrofcr on 990 and 990-EZ, compofficers on 990-PF.'}}, 'description': 'Executive compensation summary. Field varies by form type. Per-officer breakdown requires Schedule J in the source PDF.', 'additionalProperties': False}, 'program_service_revenue': {'type': ['number', 'null'], 'description': 'Program service revenue (totprgmrevnue). 990/990-EZ only; null for 990-PF.'}, 'contributions_and_grants': {'type': ['number', 'null'], 'description': 'Total contributions and grants (totcntrbgfts). 990/990-EZ only; null for 990-PF.'}}, 'description': 'Form 990 filing with extracted financial data for one fiscal year.', 'additionalProperties': False}, 'description': 'Filings with extracted financial data, sorted newest first.'}, 'data_source': {'type': 'string', 'description': 'ProPublica + IRS attribution text.'}, 'propublica_url': {'type': 'string', 'description': 'ProPublica Nonprofit Explorer URL for this org.'}, 'filings_pdf_only': {'type': 'array', 'items': {'type': 'object', 'required': ['tax_prd_yr', 'form_type_str', 'pdf_url'], 'properties': {'pdf_url': {'type': ['string', 'null'], 'description': 'Source Form 990 PDF link. Null for some batches.'}, 'tax_prd_yr': {'type': 'number', 'description': 'Fiscal year of this filing.'}, 'form_type_str': {'type': 'string', 'description': 'Form type string as returned by API ("990", "990EZ", "990PF").'}}, 'description': 'Older filing with a PDF link but no extracted financial data.', 'additionalProperties': False}, 'description': 'Older filings with a PDF but no extracted financial data.'}, 'total_filings_pdf_only': {'type': 'number', 'description': 'Count of PDF-only filings (no extracted data).'}, 'total_filings_with_data': {'type': 'number', 'description': 'Count of filings with extracted financial data.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['ein'], 'properties': {'ein': {'anyOf': [{'type': 'integer', 'maximum': 9007199254740991, 'description': 'EIN as integer (e.g., 530196605). Leading zeros are stripped â\x80\x94 treat EIN as an integer key.', 'exclusiveMinimum': 0}, {'type': 'string', 'pattern': '^\\d{2}-?\\d{7}$', 'description': 'EIN as string, with or without hyphen (e.g., "53-0196605" or "530196605").'}], 'description': 'Employer Identification Number. Accepts integer (530196605) or string with optional hyphen ("53-0196605"). Obtain from nonprofit_search results.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['ein', 'strein', 'name', 'sort_name', 'address', 'city', 'state', 'zipcode', 'ntee_code', 'subsection_code', 'ruling_date', 'asset_amount', 'income_amount', 'revenue_amount', 'deductible', 'exempt_status', 'foundation_type', 'bmf_tax_period', 'latest_filing', 'filing_count', 'data_source', 'propublica_url']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'ein': {'type': 'number', 'description': 'Employer Identification Number as integer.'}, 'city': {'type': ['string', 'null'], 'description': 'City. Null when not on record.'}, 'name': {'type': 'string', 'description': 'Legal org name per IRS.'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['not_found', 'upstream_error'], 'description': 'Machine-readable failure mode. Declared by this tool: `not_found`: The EIN does not correspond to a known organization in the Nonprofit Explorer database. `upstream_error`: ProPublica API returns a non-JSON body (HTML 500) or network error. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'state': {'type': ['string', 'null'], 'description': 'Two-letter state abbreviation. Null when not on record.'}, 'strein': {'type': 'string', 'description': 'EIN in "XX-XXXXXXX" format.'}, 'address': {'type': ['string', 'null'], 'description': 'Street address. Null when not on record.'}, 'zipcode': {'type': ['string', 'null'], 'description': 'ZIP code. Null when not on record.'}, 'ntee_code': {'type': ['string', 'null'], 'description': 'Full NTEE code (e.g., "E210" = hospital). Null when unclassified.'}, 'sort_name': {'type': ['string', 'null'], 'description': 'IRS Business Master File secondary name line (SORT_NAME) â\x80\x94 an internal sort key such as a division or service-center label, not an alternate organization name. Null for most orgs.'}, 'deductible': {'type': ['string', 'null'], 'description': 'Whether contributions to this org are tax-deductible, as "<IRS code> â\x80\x94 <meaning>". Three states, not two: code 1 deductible, code 2 not deductible, code 4 deductible by treaty (foreign orgs). Null when the IRS Business Master File records no deductibility code.'}, 'data_source': {'type': 'string', 'description': 'ProPublica + IRS attribution text.'}, 'ruling_date': {'type': ['string', 'null'], 'description': 'ISO date of IRS recognition (e.g., "1946-07"). Null when not on record.'}, 'asset_amount': {'type': ['number', 'null'], 'description': 'Most recent IRS BMF total assets in USD. Null when not on record.'}, 'filing_count': {'type': 'number', 'description': 'Total filings with extracted data on record.'}, 'exempt_status': {'type': ['string', 'null'], 'description': 'IRS exemption status as "<IRS code> â\x80\x94 <meaning>"; code 1 is an unconditional exemption. This records what the IRS granted, not whether the exemption is still in force â\x80\x94 the Business Master File is a lagging snapshot and automatic revocations are published separately. Null when the Business Master File records no status code.'}, 'income_amount': {'type': ['number', 'null'], 'description': 'Most recent IRS BMF total income in USD. Null when not on record.'}, 'latest_filing': {'anyOf': [{'type': 'object', 'required': ['tax_prd_yr', 'form_type', 'total_revenue', 'total_expenses', 'total_assets', 'total_liabilities', 'net_assets', 'pdf_url'], 'properties': {'pdf_url': {'type': ['string', 'null'], 'description': 'Source Form 990 PDF link. Null for some IRS processing batches â\x80\x94 check filings via nonprofit_get_filings.'}, 'form_type': {'enum': ['990', '990-EZ', '990-PF'], 'type': 'string', 'description': 'IRS form type filed.'}, 'net_assets': {'type': ['number', 'null'], 'description': 'Net assets/fund balances (end of year) in USD. From totnetassetend. Null when not extracted.'}, 'tax_prd_yr': {'type': 'number', 'description': 'Fiscal year of this filing (e.g., 2023). NOT the current year â\x80\x94 data lags 1â\x80\x932 years.'}, 'total_assets': {'type': ['number', 'null'], 'description': 'Total assets (end of year) in USD. Null when not extracted.'}, 'total_revenue': {'type': ['number', 'null'], 'description': 'Total revenue in USD. Null when not extracted.'}, 'total_expenses': {'type': ['number', 'null'], 'description': 'Total expenses in USD. Null when not extracted.'}, 'total_liabilities': {'type': ['number', 'null'], 'description': 'Total liabilities (end of year) in USD. Null when not extracted.'}}, 'additionalProperties': False}, {'type': 'null'}], 'description': 'Financial snapshot from the most recent Form 990. Null if no filings_with_data are available.'}, 'bmf_tax_period': {'type': ['string', 'null'], 'description': 'Tax period of the latest return recorded in the IRS Business Master File (e.g. "2025-06-01"). Often more recent than latest_filing.tax_prd_yr, which reflects the newest 990 ProPublica has extracted. Null when not on record.'}, 'propublica_url': {'type': 'string', 'description': 'ProPublica Nonprofit Explorer URL for this org.'}, 'revenue_amount': {'type': ['number', 'null'], 'description': 'Most recent IRS BMF total revenue in USD. Null when not on record.'}, 'foundation_type': {'type': ['string', 'null'], 'description': 'IRS foundation classification as "<IRS code> â\x80\x94 <meaning>", separating public charities (codes 10â\x80\x9325) from private foundations (codes 2â\x80\x934). Codes 0 (all organizations except 501(c)(3)) and 9 (suspense) fall outside both groups. Null when the IRS Business Master File records no foundation code.'}, 'subsection_code': {'type': ['number', 'null'], 'description': '501(c) subsection number (e.g., 3 = charitable organization, covering both public charities and private foundations â\x80\x94 see foundation_type to tell them apart). Null when not classified.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['query'], 'properties': {'page': {'type': 'integer', 'default': 0, 'maximum': 9007199254740991, 'minimum': 0, 'description': 'Zero-indexed page number. 25 results per page. Total pages is in num_pages. Increment to paginate large result sets.'}, 'query': {'type': 'string', 'description': 'Keyword search string. Searched against org name, the secondary name line, and city in order of relevance. Supports: quoted phrases ("Red Cross"), required terms (+evanston), excluded terms (-dental). Empty string returns all orgs within the active filters.'}, 'state': {'type': 'string', 'maxLength': 2, 'minLength': 2, 'description': 'Two-letter US state, territory, or military postal code (e.g., "WA", "NY", "PR"). Case-insensitive â\x80\x94 normalized to uppercase before filtering. A code outside that set is rejected rather than silently returning national results. Restricts results to orgs headquartered in that state. "ZZ" (foreign address) is accepted, but no organization in the index currently carries it.'}, 'ntee_category': {'enum': ['1', '2', '3', '4', '5', '6', '7', '8', '9', '10'], 'type': 'string', 'description': 'NTEE (National Taxonomy of Exempt Entities) major group integer (1â\x80\x9310). 1=Arts/Culture/Humanities, 2=Education, 3=Environment/Animals, 4=Health, 5=Human Services, 6=International/Foreign Affairs, 7=Public/Societal Benefit, 8=Religion Related, 9=Mutual/Membership Benefit, 10=Unknown/Unclassified.'}, 'subsection_code': {'enum': ['2', '3', '4', '5', '6', '7', '8', '9', '10', '11', '12', '13', '14', '15', '16', '17', '18', '19', '21', '22', '23', '25', '26', '27', '28', '92'], 'type': 'string', 'description': '501(c) subsection code. "3" = charitable/religious/educational organization (most common â\x80\x94 includes both public charities and private foundations; nonprofit_get_organization returns foundation_type to tell them apart), "4" = social welfare org, "6" = business league/trade association, "92" = 4947(a)(1) nonexempt charitable trust. Filters by tax status, not sector.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['total_results', 'num_pages', 'cur_page', 'per_page', 'page_offset', 'organizations', 'active_filters', 'data_source']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['invalid_state', 'pagination_ceiling', 'upstream_error'], 'description': "Machine-readable failure mode. Declared by this tool: `invalid_state`: The state filter is not a US state, territory, or military postal code (or ZZ for foreign entities). `pagination_ceiling`: The requested page is at or beyond ProPublica's 10,000-result offset ceiling. `upstream_error`: ProPublica API returns a 500 or network error. Other values are possible when a failure originates below the handler."}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'notice': {'type': 'string', 'description': 'Present when the response needs a caveat the domain fields cannot carry: a page that returned no organizations (distinguishing a zero-match query from a page past the end of the result set, and naming the next call), a total_results sitting on the API result ceiling rather than counting matches, or both at once in one string. Absent when the page is populated and the total is an exact count.'}, 'cur_page': {'type': 'number', 'description': 'Current page (zero-indexed).'}, 'per_page': {'type': 'number', 'description': 'Results per page applied by the API (25).'}, 'num_pages': {'type': 'number', 'description': 'Total pages available (total_results / 25, ceiling). The last valid page is num_pages - 1.'}, 'data_source': {'type': 'string', 'description': 'ProPublica + IRS attribution text.'}, 'page_offset': {'type': 'number', 'description': 'Zero-indexed offset of the first result on this page. Requests are refused once this reaches 10,000.'}, 'organizations': {'type': 'array', 'items': {'type': 'object', 'required': ['ein', 'strein', 'name', 'sub_name', 'city', 'state', 'ntee_code', 'subseccd', 'score'], 'properties': {'ein': {'type': 'number', 'description': 'Employer Identification Number â\x80\x94 use with nonprofit_get_organization and nonprofit_get_filings.'}, 'city': {'type': ['string', 'null'], 'description': 'Headquarters city. Null when not on record.'}, 'name': {'type': 'string', 'description': 'Legal org name per IRS.'}, 'score': {'type': 'number', 'description': 'Relevance score â\x80\x94 higher = better match.'}, 'state': {'type': ['string', 'null'], 'description': 'Two-letter state abbreviation. Null when not on record.'}, 'strein': {'type': 'string', 'description': 'EIN in "XX-XXXXXXX" format (preserves leading zeros).'}, 'sub_name': {'type': ['string', 'null'], 'description': 'The legal name with the IRS Business Master File secondary name line appended â\x80\x94 a division, service-center, or chapter identifier, not a separate trade name the org operates under. Null when the org has no secondary name line.'}, 'subseccd': {'type': ['number', 'null'], 'description': '501(c) subsection code (e.g., 3 = charitable organization). Null when not classified.'}, 'ntee_code': {'type': ['string', 'null'], 'description': 'Full NTEE code (e.g., "E210" = hospital). More specific than the ntee_category filter.'}}, 'description': 'A matched tax-exempt organization.', 'additionalProperties': False}, 'description': 'Matching organizations for the current page.'}, 'total_results': {'type': 'number', 'description': 'Total matching orgs (up to 10,000 â\x80\x94 the API ceiling). If 10000, actual count may be higher.'}, 'active_filters': {'type': 'object', 'required': ['query', 'state', 'ntee_category', 'subsection_code'], 'properties': {'query': {'type': 'string', 'description': 'Search query as submitted.'}, 'state': {'type': ['string', 'null'], 'description': 'State filter applied, or null.'}, 'ntee_category': {'type': ['string', 'null'], 'description': 'NTEE major group filter applied, or null.'}, 'subsection_code': {'type': ['string', 'null'], 'description': '501(c) subsection filter applied, or null.'}}, 'description': 'Active filters echoed back for verification.', 'additionalProperties': False}}, 'additionalProperties': False}