nonprofit-explorer-mcp-server

---

概览

通过 ProPublica Nonprofit Explorer API 获取 180 多万个免税组织的 IRS Form 990 数据。按名称搜索、获取组织的财务概况，并查看其完整申报历史。

工具

工具	描述
nonprofit_search_organizations	按名称、关键词、城市或短语搜索 180 多万个获 IRS 认可的免税组织；可选按州、NTEE 行业类别和 501(c) 筛选
nonprofit_get_organization	按 EIN 获取单个组织的完整档案：法定身份、IRS 分类、裁定日期，以及来自最新 Form 990 的财务概况
nonprofit_get_filings	按 EIN 获取某组织的所有 Form 990 申报记录：逐年财务数据、收入明细、高管薪酬和源 PDF 链接

功能参考

nonprofit_search_organizations _工具

• 全文查询——支持带引号的短语（"Red Cross"）、必需词项（+evanston）和排除词项（-dental）
• 可选筛选条件：美国州／领地或军事邮政编码（外国实体使用 ZZ；不在该集合中的代码会被拒绝，而不会悄悄返回全国范围的结果）、NTEE 主要类别（1–10）、501(c) 子条款代码（3 同时涵盖公共慈善机构和私人基金会——可通过 nonprofit_get_organization 中的 foundation_type 区分）
• 支持分页，每页 25 条（page 从 0 开始）；num_pages、per_page 和 page_offset 用于跟踪位置
• API 将结果总数限制为 10,000——total_results === 10000 表示实际数量可能更多；若某页的偏移量达到上限，则会被拒绝（pagination_ceiling）
• 无匹配结果和请求页码超出最后一页都会成功返回空的 organizations 数组，并通过 notice 说明具体情况
• 返回 EIN——可将其传给 nonprofit_get_organization 或 nonprofit_get_filings 获取详情

---

nonprofit_get_organization _工具

• 接受整数形式的 EIN（530196605），或带连字符／不带连字符的字符串（"53-0196605"）；如果只有组织名称，请先使用 nonprofit_search_organizations
• 返回法定身份、地址、NTEE 代码、501(c) 类型和 IRS 裁定日期
• IRS Business Master File 状态：可抵扣性（包括根据条约可抵扣的情况）、免税状态，以及公共慈善机构与私人基金会的分类——各项均根据 IRS 代码解码，同时保留原始代码
• 最近一期 Form 990 的财务概况：收入、支出、资产、负债、净资产，以及来源 PDF 链接
• filing_count 统计已提取数据的申报记录；filing_count_pdf_only 单独统计没有财务数据提取结果的 PDF。请使用 nonprofit_get_filings 获取这些链接；仅有 PDF 的历史记录没有财务概况
• 数据有 1–2 年延迟——概况中的 tax_prd_yr 是申报的财政年度，而非当前年份

---

nonprofit_get_filings _工具

• 返回所有已提取数据的 Form 990 申报记录，按时间从新到旧排序——每份申报包括：收入、支出、资产、负债、净资产、收入明细（捐款、项目服务收入、投资收入）和来源 PDF 链接
• 财务字段因各申报表类型而异。对于 990-PF，投资收入为储蓄利息加股息和证券利息（Part I 第 (a) 列，第 3–4 行）；必须提取这两个组成部分。不包括资本利得、租金和净投资收入
• 990-PF 申报记录包含 grants_paid、distributable_amount、fair_market_value_assets 和 net_investment_income。可分配金额是支出要求，并不代表实际付款或合规情况
• program_expense_ratio 始终为 null——ProPublica 不会返回 Form 990 Part IX 中项目服务支出总额，因此项目／管理／筹款支出明细仅见于来源 PDF
• 高管薪酬摘要会明确说明字段名称，并注明可在 Schedule J 中查看各位高管的详细信息
• filings_pdf_only 列出较早的申报记录，这些记录有 PDF，但没有提取数据
• 如果 EIN 对应的是真实组织，但没有 990 申报记录，则返回空的 filings 数组及 notice，而非错误
• 数据有 1–2 年延迟——展示数值时务必注明 tax_prd_yr（财政年度）

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔的身份验证（none / jwt / oauth）、可切换的存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及支持可选 OpenTelemetry 跟踪的结构化日志记录。

ProPublica Nonprofit Explorer / IRS 专属功能：

• 免密钥访问 — ProPublica Nonprofit Explorer API 无需 API 密钥
• 覆盖 180 多万家获 IRS 认可的免税组织
• IRS Form 990 数据：涵盖公共慈善机构（990）、小型组织（990-EZ）和私人基金会（990-PF）的年度申报
• 每条申报记录均包含原始申报 PDF 链接；但 IRS PDF 处理可能滞后于数据提取，此时 pdf_url 仍为 null
• 数据来源于 ProPublica Nonprofit Explorer，基于 IRS Form 990 申报；数据滞后 1–2 年

适合 Agent 使用的输出：

• 每个响应均注明来源 — 所有工具输出均包含 data_source 归属信息，以及可直接核验的 ProPublica URL
• 明确标注申报年度 — tax_prd_yr 显著标注为财年，并在每个财务响应中明确提示数据滞后
• 显示 null 值，不予省略 — 格式化文本会说明值缺失的原因（IRS 从未记录、未从申报中提取，或该表格类型不包含此项）；structuredContent 会保留明确的 null，而非省略该键
• 薪酬字段透明可查 — 提供 field_name 和 form_type，让 Agent 清楚了解读取的是哪个 IRS 字段

开始使用

公共托管实例

可通过 https://nonprofit-explorer.caseyjhand.com/mcp 使用公共实例 — 无需安装。将任意 MCP 客户端配置为通过 Streamable HTTP 连接，并使用以下客户端配置：

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

自托管 / 本地使用

将以下内容添加到 MCP 客户端配置文件中。

{
  "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"
      }
    }
  }
}

也可通过 npx 运行（无需 Bun）：

{
  "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"
      }
    }
  }
}

或通过 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"
      ]
    }
  }
}

如需使用 Streamable HTTP，请设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前提条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 无需 API 密钥 — ProPublica Nonprofit Explorer 是免密钥公共 API。

安装

1. 克隆仓库：

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

2. 进入目录：

cd nonprofit-explorer-mcp-server

3. 安装依赖：

bun install

4. 配置环境：

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

配置

所有配置都会在启动时进行验证。主要环境变量：

变量	说明	默认值
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http	stdio
MCP_HTTP_PORT	HTTP 服务端口	3010
MCP_HTTP_HOST	HTTP 服务主机名	127.0.0.1
MCP_HTTP_ENDPOINT_PATH	HTTP 端点路径	/mcp
MCP_PUBLIC_URL	TLS 终止反向代理部署的公共源覆盖值	—
MCP_AUTH_MODE	身份验证：none、jwt 或 oauth	none
MCP_LOG_LEVEL	日志级别（debug、info、warning、error 等）	info
LOGS_DIR	日志文件目录（仅限 Node.js）	<project-root>/logs
LOG_TOOL_FAILURE_PAYLOADS	记录每次失败的工具调用参数和结果，按键名进行脱敏，并限制在 LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES 字节以内（默认 16384）。自由格式值中的密钥不会被脱敏。	false
STORAGE_PROVIDER_TYPE	存储后端：in-memory、filesystem、supabase、cloudflare-kv/r2/d1	in-memory
OTEL_ENABLED	启用 OpenTelemetry 插桩	false

没有服务专属的必需变量。ProPublica Nonprofit Explorer 是免密钥公共 API。

完整的可选覆盖项列表请参阅 .env.example。

运行服务

本地开发

• 构建并运行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t nonprofit-explorer-mcp-server .
docker run --rm -p 3010:3010 nonprofit-explorer-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/nonprofit-explorer-mcp-server。默认安装 OpenTelemetry 对等依赖；构建时使用 --build-arg OTEL_ENABLED=false 可省略这些依赖。

项目结构

目录	用途
src/index.ts	createApp() 入口点 — 注册工具并初始化服务。
src/mcp-server/tools	工具定义（*.tool.ts）。提供用于搜索和财务数据的 3 个工具。
src/services/nonprofit-explorer	ProPublica Nonprofit Explorer API 客户端和领域类型。
tests/	与 src/ 结构对应的单元测试和集成测试。

开发指南

开发指南和架构规则请参阅 CLAUDE.md/AGENTS.md。简要概括如下：

• 处理程序负责抛出异常，框架负责捕获 — 工具逻辑中不要使用 try/catch
• 使用 ctx.log 进行请求级日志记录，使用 ctx.state 进行租户级存储
• 在 src/index.ts 的 createApp() 中，通过数组注册新工具
• 封装外部 API 调用：校验原始数据 → 规范化为领域类型 → 返回输出架构；绝不编造缺失字段

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0 — 详情请参阅 LICENSE。