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
🚀 One-Click Deployment
Deploy the ProPublica MCP server instantly to your preferred cloud platform:
Cloudflare Workers
Both platforms offer:
- DigitalOcean: Container-based deployment with automatic scaling and monitoring
- Cloudflare: Serverless deployment with global edge distribution and zero cold starts
Quick Start
Prerequisites
Installation
Option 1: Docker (Recommended)
The easiest way to run the ProPublica MCP server is using Docker:
Quick Start with Docker:
# Pull the latest image from GitHub Container Registry
docker pull ghcr.io/asachs/propublica-mcp:latest
# Run the server
docker run -it --rm ghcr.io/asachs/propublica-mcp:latest
Using Docker Compose:
- Download the compose file:
curl -O https://raw.githubusercontent.com/asachs/propublica-mcp/main/docker-compose.yml
curl -O https://raw.githubusercontent.com/asachs/propublica-mcp/main/env.example
- Configure environment (optional):
cp env.example .env
# Edit .env file with your preferred settings
- Start the service:
Option 2: Cloud Deployment
DigitalOcean App Platform:
- Click the "Deploy to DO" button above
- Connect your GitHub account (if not already connected)
- Configure environment variables (optional - defaults are provided)
- Click "Deploy" - your app will be live in minutes with a public URL
Cloudflare Workers:
- Click the "Deploy to Cloudflare Workers" button above
- Connect your GitHub account and authorize Cloudflare
- Configure any environment variables as needed
- Deploy - your serverless function will be live globally
🚀 Production Deployment Strategy
Cloud deployments only deploy from the deploy branch, which contains stable, tested releases:
- Development: All work happens on
main branch - Releases: When tags are created (e.g.,
v0.2.0), the deploy branch is automatically updated - Cloud Platforms: DigitalOcean and Cloudflare deploy only from the
deploy branch - Benefits: Ensures only stable, released versions reach production environments
Option 3: Local Python Installation
- Clone the repository:
git clone <repository-url>
cd propublica-mcp
- Create and activate a virtual environment:
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
- Install dependencies:
pip install -r requirements.txt
- Install the package:
- Run the server:
For stdio mode (local MCP clients):
python -m propublica_mcp.server
For HTTP mode (remote MCP clients):
python -m propublica_mcp.server --http --host 0.0.0.0 --port 8080
Available options:
--http: Enable HTTP server mode for remote MCP clients--host: Host to bind to (default: 127.0.0.1)--port: Port to bind to (default: 8080)--log-level: Set logging level (DEBUG, INFO, WARNING, ERROR)
Usage with MCP Clients
This server implements the MCP 2025-03-26 Streamable HTTP transport protocol and can be used with any MCP client, including Claude Desktop, Cursor, and other compatible tools.
For Cloud Deployment (Remote MCP Server):
DigitalOcean/Cloudflare (Streamable HTTP):
For remote Python MCP servers, you'll need to use an HTTP transport. Add this to your MCP client configuration:
{
"mcpServers": {
"propublica-mcp": {
"transport": {
"type": "http",
"url": "https://propublica-mcp-lk97f.ondigitalocean.app"
},
"description": "ProPublica Nonprofit Explorer MCP Server (Remote)"
}
}
}
For Local Installation (stdio transport):
{
"mcpServers": {
"propublica-mcp": {
"command": "python",
"args": ["-m", "propublica_mcp.server"],
"cwd": "/path/to/propublica-mcp",
"env": {}
}
}
}
For Docker Deployment (stdio transport):
{
"mcpServers": {
"propublica-mcp": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"ghcr.io/asachs/propublica-mcp:latest"
],
"description": "ProPublica Nonprofit Explorer MCP Server"
}
}
}
For Local HTTP Server (development):
# Start HTTP server locally
python -m propublica_mcp.server --http --host 0.0.0.0 --port 8080
Then configure as remote server:
{
"mcpServers": {
"propublica-mcp": {
"transport": {
"type": "http",
"url": "http://localhost:8080"
},
"description": "ProPublica Nonprofit Explorer MCP Server (Local HTTP)"
}
}
}
- search_nonprofits: Search for nonprofit organizations
- get_organization: Get detailed organization information by EIN
- get_organization_filings: Retrieve Form 990 filings for an organization
- 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/
├── src/
│ └── propublica_mcp/
│ ├── __init__.py
│ ├── server.py
│ ├── api_client.py
│ ├── models.py
│ └── tools/
├── tests/
├── config/
├── .github/
│ └── workflows/
├── Dockerfile
├── docker-compose.yml
├── env.example
├── requirements.txt
└── README.md
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/asachs/propublica-mcp:latest \
python -m pytest tests/ -v
# Or with docker compose
docker compose run --rm propublica-mcp pytest tests/ -v
Publishing to GitHub Container Registry
The project includes automated publishing via GitHub Actions, but you can also publish manually:
Prerequisites
- GitHub Personal Access Token with
packages:write scope - Authentication to GitHub Container Registry:
echo $GITHUB_TOKEN | docker login ghcr.io -u YOUR_USERNAME --password-stdin
Automated Publishing (Recommended)
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
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 Images
Once published, the images will be available at:
- Latest:
ghcr.io/asachs/propublica-mcp:latest - Tagged versions:
ghcr.io/asachs/propublica-mcp:v1.0.0 - Branch builds:
ghcr.io/asachs/propublica-mcp:main
Contributing
- Follow the existing code style
- Add tests for new features
- Update documentation as needed
- Ensure all tests pass before submitting
License
MIT License - see LICENSE file for details
Support
For issues and questions:
- Check the documentation
- Review existing GitHub issues
- Create a new issue with detailed information