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

🔎 Charity Search

• 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

Quick Start

Prerequisites

• Node.js 18+

• npm or yarn

• CharityAPI account and API key

Installation

1. Clone the repository

   git clone <repository-url> cd charity-mcp-server

2. Install dependencies

   npm install

3. Configure environment variables

   cp .env.example .env # Edit .env with your API key and configuration

4. Build the project

   npm run build

5. Start the server

   npm start

Configuration

Environment Variables

Create a .env file based on .env.example:

API Key Setup

1. Sign up for a CharityAPI account

2. Generate an API key from your dashboard

3. Add the API key to your .env file

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:

Returns:

• Complete organization details

• Tax deductibility status and codes

• Organization classification and activity codes

• Current IRS status and ruling information

2. Charity Search (charity_search)

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:

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:

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:

Usage with MCP Clients

Claude Desktop

Add to your Claude Desktop configuration:

Other MCP Clients

The server implements the standard MCP protocol and works with any compatible client. Connect using stdio transport.

Development

Project Structure

Development Commands

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

Contributing

1. Fork the repository

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

Development Guidelines

• Maintain TypeScript strict mode compliance

• Add comprehensive input validation for new features

• Include error handling with user-friendly messages

• Update schemas and types for new data structures

• Add logging for debugging and monitoring

• Follow existing code organization patterns

License

This project is licensed under the MIT License - see the LICENSE file for details.

Prompt Examples & Usage

For AI assistants using this MCP server, see our comprehensive prompt guides:

• Verification Prompts Guide - Detailed workflows and examples for charity verification

• Quick Reference - Fast lookup templates and best practices

Example Verification Prompts

Basic Legitimacy Check:

• "Is the American Red Cross a real charity registered with the IRS?"

• "Verify that organization with EIN 13-1837418 is legitimate"

• "Quick check: is EIN 52-1693387 a legitimate public charity?"

Suspicious Organization Verification:

• "I got a donation request from 'Help Kids Foundation' - are they legitimate?"

• "Someone is collecting money for hurricane relief - EIN 12-3456789. Is it real?"

Location-Specific Verification:

• "Is there a legitimate charity called 'Local Food Bank' in Chicago, IL?"

• "Verify 'Animal Rescue' operating in California"

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

Acknowledgments

• Model Context Protocol for the standard

• CharityAPI.org for nonprofit data access

• The open source community for inspiration and contributions