# propublica-npo-mcp

MCP server exposing the ProPublica Nonprofit Explorer API with curated nonprofit and filing summaries.

## Install

```bash
npm install
```

## Run

```bash
npm run start
```

For local development:

```bash
npm run dev
```

## Claude Desktop / Cline config

```json
{
  "mcpServers": {
    "propublica-npo": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/propublica-npo-mcp/src/index.ts"]
    }
  }
}
```

## Tools

`search_nonprofits` searches the ProPublica Nonprofit Explorer index by name or keyword, with optional state, NTEE major category, 501(c) subtype, and page filters.

`get_organization` returns organization metadata plus a curated summary of up to five most recent filings by default. Pass `verbose: true` to get the raw upstream payload.

`list_organization_filings` returns all filings for an EIN, newest first. The default output is curated; `verbose: true` returns the raw filing arrays.

`compare_nonprofits` compares 2-5 organizations side by side using their latest filing with data, while preserving per-EIN 404s as row-level errors.

## Notes

The server uses a 100-entry in-memory LRU cache with a 1-hour TTL. Each upstream request has a 15-second timeout and retries once on network or 5xx failures. ProPublica is public but still rate-limited; if you hit a 429, wait and retry rather than looping.

---

## Support

If this project helps you research nonprofits or build cool agents, consider buying me a coffee! It helps keep the updates coming.

<a href="https://paypal.me/2b3/5">
  <img src="https://img.shields.io/badge/Donate-PayPal-blue.svg" alt="Donate with PayPal" />
</a>

**[https://paypal.me/2b3/5](https://paypal.me/2b3/5)**

---

## License

MIT License - Created by [Ian Shen](https://github.com/2b3pro).