Labsco
asachs01 logo

ProPublica MCP Server

★ 1

from asachs01

Search and analyze nonprofit organizations' Form 990 data using ProPublica's Nonprofit Explorer API.

🔥🔥🔥✓ VerifiedFreeAdvanced setup
#automation#crm#lead-gen#cloud#devops#git#maps#monitoring

ProPublica MCP Server

A Model Context Protocol (MCP) server that provides access to ProPublica's Nonprofit Explorer API, enabling AI models to search and analyze nonprofit organizations' Form 990 data for CRM integration and prospect research.

🚨 Breaking Changes in v1.0.0

Version 1.0.0 introduces breaking changes with the implementation of MCP 2025-03-26 Streamable HTTP transport:

  • Remote deployments now use a single / endpoint instead of /sse and /messages
  • MCP client configuration has changed for cloud deployments (see Usage section below)
  • Improved compatibility with Claude Desktop, Cursor, and other MCP clients
  • Backwards incompatible with MCP clients expecting the old SSE transport

Features

  • Search nonprofit organizations by name, location, and category
  • Retrieve detailed organization profiles and contact information
  • Access Form 990 financial data and filing history
  • Analyze financial trends across multiple years
  • Export data in CRM-ready formats
  • Built with FastMCP for optimal performance

API Tools

Core Tools

  • search_nonprofits: Search for nonprofit organizations
  • get_organization: Get detailed organization information by EIN
  • get_organization_filings: Retrieve Form 990 filings for an organization

Advanced Tools

  • analyze_nonprofit_financials: Analyze financial trends across multiple years
  • search_similar_nonprofits: Find similar organizations
  • export_nonprofit_data: Format data for CRM import

Data Sources

This server uses the ProPublica Nonprofit Explorer API which provides:

  • IRS Form 990 data for tax-exempt organizations
  • Organization profiles and contact information
  • Financial data and filing history
  • NTEE categorization and 501(c) status

Development

Project Structure

propublica-mcp/
├── server/                    # DXT extension structure
│   ├── src/
│   │   └── propublica_mcp/
│   │       ├── __init__.py
│   │       ├── server.py
│   │       ├── api_client.py
│   │       ├── models.py
│   │       └── tools/
│   ├── requirements.txt
│   └── manifest.json         # DXT extension manifest
├── src/                      # Legacy source structure (for compatibility)
│   └── propublica_mcp/
├── tests/
├── config/
├── .github/
│   └── workflows/
│       └── build-dxt.yml     # Automated DXT packaging
├── Dockerfile
├── docker-compose.yml
├── env.example
├── requirements.txt
├── manifest.json             # Root DXT manifest
└── README.md

The project now supports both the traditional Python package structure and the new DXT extension format. The server/ directory contains the DXT-compatible structure that gets packaged into .dxt files during releases.

Development with Docker

Building the Docker Image

# Build the image
docker build -t propublica-mcp:dev .

# Or use docker-compose
docker-compose build

Running Development Environment

# Run with docker-compose (includes volume mounts for development)
docker-compose -f docker-compose.yml -f docker-compose.override.yml up

# Run tests in container
docker run --rm -v $(pwd):/app propublica-mcp:dev pytest tests/ -v

Environment Variables

The Docker container supports these environment variables:

  • LOG_LEVEL: Set logging level (DEBUG, INFO, WARNING, ERROR)
  • API_RATE_LIMIT: Requests per minute (default: 60)
  • PROPUBLICA_API_BASE_URL: API base URL (rarely needs changing)

Running Tests

Local Testing

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ -v --cov=src/propublica_mcp

Docker Testing

# Run tests in Docker
docker run --rm ghcr.io/asachs01/propublica-mcp:latest \
  python -m pytest tests/ -v

# Or with docker compose
docker compose run --rm propublica-mcp pytest tests/ -v

Building DXT Extensions

The project includes automated DXT packaging via GitHub Actions. DXT files are automatically built and attached to releases.

Create a tag to trigger automated DXT packaging:

# Create and push a version tag
git tag v1.0.0
git push origin v1.0.0

This will:

  1. Package the server/ directory into a .dxt file
  2. Create a GitHub release with the DXT file attached
  3. Build and publish Docker images to GitHub Container Registry

Manual DXT Building

For development or testing:

# Create DXT package manually
cd server/
zip -r ../propublica-mcp-dev.dxt .

Publishing to GitHub Container Registry

The project includes automated publishing via GitHub Actions, but you can also publish manually:

Prerequisites

  1. GitHub Personal Access Token with packages:write scope
  2. Authentication to GitHub Container Registry: 
    echo $GITHUB_TOKEN | docker login ghcr.io -u YOUR_USERNAME --password-stdin

Push to the main branch or create a tag to trigger automated builds:

# Trigger build for main branch
git push origin main

# Create and push a version tag (also builds DXT)
git tag v1.0.0
git push origin v1.0.0

Manual Publishing

Use the provided script (requires local setup):

# Build and publish latest
./scripts/docker-publish.sh

# Build and publish specific version
./scripts/docker-publish.sh v1.0.0

Available Packages

Once published, the following packages will be available:

DXT Extensions:

  • Latest: Available from GitHub releases
  • Tagged versions: propublica-mcp-v1.0.0.dxt
  • Direct download: https://github.com/asachs01/propublica-mcp/releases/latest/download/propublica-mcp.dxt

Docker Images:

  • Latest: ghcr.io/asachs01/propublica-mcp:latest
  • Tagged versions: ghcr.io/asachs01/propublica-mcp:v1.0.0
  • Branch builds: ghcr.io/asachs01/propublica-mcp:main

Contributing

  1. Follow the existing code style
  2. Add tests for new features
  3. Update documentation as needed
  4. Ensure all tests pass before submitting

Support

For issues and questions:

  • Check the documentation
  • Review existing GitHub issues
  • Create a new issue with detailed information