nonprofit-explorer-mcp-server

---

概要

ProPublica Nonprofit Explorer API を介して、非課税団体 180 万以上の IRS Form 990 データを利用できます。団体名で検索し、団体の財務スナップショットを取得し、申告履歴全体を確認できます。

ツール

ツール	説明
nonprofit_search_organizations	名前、キーワード、市、フレーズで IRS 認定の非課税団体 180 万以上を検索します。州、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を参照してください）
• 1ページあたり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 column (a), lines 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 固有の機能：

• API キー不要のアクセス — ProPublica Nonprofit Explorer API では API キーは不要です
• IRS が認定する非課税組織を 180 万件以上収録
• IRS Form 990 データ：公益慈善団体（990）、小規模組織（990-EZ）、民間財団（990-PF）の年次申告書
• IRS の PDF 処理が抽出データに追いついておらず、pdf_url がまだ null の場合を除き、各申告記録に原本申告書の PDF リンクを掲載
• データは ProPublica Nonprofit Explorer を出典とし、IRS Form 990 の申告書に基づいています。データには 1～2 年の遅れがあります

エージェントが使いやすい出力：

• すべての応答に出典情報を付与 — すべてのツール出力に data_source の出典表示があり、直接確認できる ProPublica の URL も含まれます
• 申告年度を明確に表示 — tax_prd_yr を会計年度として目立つように示し、すべての財務情報の応答に遅延についての明示的な注意書きを含めます
• null 値を省略せずに表示 — 整形済みテキストでは、値がない理由（IRS に記録されていない、申告書から抽出されていない、該当する様式では引き継がれない）を明記し、structuredContent ではキーを省略せず、明示的な null を保持します
• 報酬のフィールド名を明示 — field_name と form_type を公開するため、エージェントは読み取った IRS フィールドを正確に把握できます

はじめに

公開ホストインスタンス

公開インスタンスを https://nonprofit-explorer.caseyjhand.com/mcp で利用できます。インストールは不要です。以下のクライアント設定を使用して、Streamable HTTP 経由で任意の MCP クライアントを接続してください。

{
  "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 キー不要の公開 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 instrumentation を有効にします	false

サーバー固有の必須変数はありません。ProPublica Nonprofit Explorer は API キー不要の公開 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 呼び出しはラップし、生データを検証してからドメイン型に正規化し、出力スキーマに従って返してください。不足しているフィールドを捏造しないでください。

コントリビューション

Issue を歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

Apache-2.0。詳細は LICENSE を参照してください。