Labsco
briancasteel logo

Charity MCP Server

★ 2

from briancasteel

Access charity and nonprofit organization data from the IRS database via CharityAPI.org.

🔥🔥🔥✓ VerifiedAccount requiredAdvanced setup
#automation#database#git#maps#security#monitoring

Charity MCP Server

A comprehensive Model Context Protocol (MCP) server that provides AI assistants with enterprise-grade access to charity and nonprofit organization data from the IRS database. This feature-complete server enables AI tools to look up charity information, verify tax-deductible status, search for nonprofit organizations, and utilize advanced prompt templates for guided charity research workflows.

🎯 Project Status: Feature Complete

Achievement: 100% complete implementation exceeding all original requirements

  • ✅ All 4 core MCP tools with comprehensive error handling
  • ✅ Complete prompt system with 14 specialized templates
  • ✅ Enterprise-grade architecture with full type safety
  • ✅ Production-ready with comprehensive testing and documentation
  • ✅ Advanced features providing superior user experience

Features

🔍 Charity Lookup

  • Look up detailed information about any charity using their EIN (Tax ID)
  • Get comprehensive IRS data including official name, location, tax status, and classification codes
  • Validate EIN format and business rules
  • Search for charities by organization name, city, or state
  • Support for pagination and filtering
  • Find organizations when you don't have their exact EIN

✅ Public Charity Verification

  • Quickly verify if an organization qualifies as a tax-deductible public charity
  • Check 501(c)(3) status for donation planning
  • Instant verification of tax-deductible status

📝 Advanced Prompt System (14 Templates)

  • 8 Verification Prompts: Complete charity verification workflows with guided steps
  • 6 Quick Reference Prompts: Streamlined lookup assistance and best practices
  • Dynamic Generation: Template-driven prompts with parameter substitution
  • User Experience: Pre-built workflows for common charity research scenarios
  • AI Assistant Guidance: Best practices and decision trees for optimal tool usage

🛡️ Enterprise Features

  • Rate Limiting: Configurable API rate limits to prevent abuse
  • Input Validation: Comprehensive validation with security checks
  • Error Handling: Robust error handling with user-friendly messages
  • Logging: Detailed logging for monitoring and debugging
  • Type Safety: Full TypeScript implementation with Zod schemas

Available Tools

1. Charity Lookup (charity_lookup)

Look up detailed information about a specific charity using their EIN.

Input:

  • ein (string, required): EIN in format "XX-XXXXXXX" or "XXXXXXXXX"

Example:

{
  "ein": "13-1837418"
}

Returns:

  • Complete organization details
  • Tax deductibility status and codes
  • Organization classification and activity codes
  • Current IRS status and ruling information

Search for charities by name, location, or other criteria.

Input:

  • query (string, optional): Organization name or keywords
  • city (string, optional): Filter by city name
  • state (string, optional): Filter by state (2-letter code)
  • limit (number, optional): Results per page (1-100, default 25)
  • offset (number, optional): Skip results for pagination (default 0)

Example:

{
  "query": "American Red Cross",
  "state": "CA",
  "limit": 10
}

Returns:

  • List of matching organizations
  • Pagination information
  • Basic details (name, EIN, location, deductibility)

3. Public Charity Check (public_charity_check)

Verify if an organization qualifies as a tax-deductible public charity.

Input:

  • ein (string, required): EIN in format "XX-XXXXXXX" or "XXXXXXXXX"

Example:

{
  "ein": "13-1837418"
}

Returns:

  • Public charity status (yes/no)
  • Tax-deductible donation eligibility
  • EIN confirmation

Available Prompts

The server provides built-in prompts to help AI assistants perform charity verification effectively:

Verification Prompts

  1. Charity Verification Guide (charity_verification_guide)

    • Complete guide for performing charity legitimacy verification
    • Customizable by organization type (name_only, ein_based, suspicious, etc.)

  2. Basic Legitimacy Workflow (basic_legitimacy_workflow)

    • Step-by-step workflows for different verification scenarios
    • Parameters: verification_type, organization_name, ein, location

  3. Red Flag Detection (red_flag_detection)

    • Guidance for detecting and handling problematic charity statuses
    • Handles revoked, conditional, and suspended organizations

  4. Verification Response Templates (verification_response_templates)

    • Standardized response formats for different verification outcomes
    • Templates for verified, failed, conditional, and not_found cases

Quick Reference Prompts

  1. Quick Verification Reference (quick_verification_reference)

    • Fast lookup templates for common verification scenarios
    • Customizable by user input type

  2. Response Templates Quick (response_templates_quick)

    • Quick response templates with status indicators (✅ ⚠️ ❌)
    • Templates for verified, cannot_verify, and problems_found cases

  3. Tool Selection Guide (tool_selection_guide)

    • Decision tree for selecting the right MCP tool
    • Scenario-specific guidance for different verification contexts

  4. Common Keywords Reference (common_keywords_reference)

    • Reference of keywords that trigger charity verification
    • Intent recognition patterns for AI assistants

  5. AI Assistant Best Practices (ai_assistant_best_practices)

    • Comprehensive best practices for using the charity verification system
    • Guidelines for communication, error handling, and user experience

Using Prompts

AI assistants can access these prompts through the MCP protocol:

{
  "method": "prompts/get",
  "params": {
    "name": "basic_legitimacy_workflow",
    "arguments": {
      "verification_type": "organization_name",
      "organization_name": "American Red Cross"
    }
  }
}

Development

Project Structure

src/
├── config/          # Configuration management
├── formatting/      # Response formatting utilities
├── prompts/         # MCP prompt implementations and templates
├── schemas/         # Zod validation schemas
├── services/        # External API clients and rate limiting
├── tools/           # MCP tool implementations
├── transformers/    # Data transformation utilities
├── types/           # TypeScript type definitions
├── utils/           # Logging, error handling, validation
└── validation/      # Input validation and sanitization

Development Commands

# Install dependencies
npm install

# Run in development mode with hot reload
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Clean build artifacts
npm run clean

# Run tests (when implemented)
npm test

# Run linting (when configured)
npm run lint

Architecture

The server follows a layered architecture:

  1. MCP Layer: Handles protocol communication and tool registration
  2. Validation Layer: Input sanitization and validation with Zod schemas
  3. Service Layer: External API communication with rate limiting
  4. Transform Layer: Data transformation and standardization
  5. Formatting Layer: Response formatting for optimal AI consumption

Key Components

  • Input Validation: EIN format validation, security sanitization
  • Rate Limiting: Token bucket algorithm with configurable limits
  • Error Handling: Structured error responses with user-friendly messages
  • Logging: Structured logging with configurable levels
  • Type Safety: Full TypeScript coverage with runtime validation

API Reference

CharityAPI Integration

This server integrates with CharityAPI.org to provide:

  • Access to complete IRS nonprofit database
  • Real-time charity information lookup
  • Organization search and filtering capabilities
  • Tax-deductible status verification

Rate Limiting

Default rate limits:

  • 100 requests per minute per tool
  • Configurable via environment variables
  • Automatic cleanup of expired tokens

Support

  • Issues: Report bugs and feature requests via GitHub Issues
  • Documentation: Additional documentation available in the /docs folder
  • CharityAPI: For API-related questions, visit CharityAPI.org