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
-
Clone the repository
git clone <repository-url> cd charity-mcp-server -
Install dependencies
npm install -
Configure environment variables
cp .env.example .env # Edit .env with your API key and configuration -
Build the project
npm run build -
Start the server
npm start
Configuration
Environment Variables
Create a .env file based on .env.example:
# CharityAPI Configuration
CHARITY_API_BASE_URL=https://api.charityapi.org
CHARITY_API_KEY=your_api_key_here
CHARITY_API_TIMEOUT=10000
CHARITY_API_MAX_RETRIES=3
CHARITY_API_RETRY_DELAY=1000
# Server Configuration
MAX_CONCURRENT_REQUESTS=10
REQUEST_TIMEOUT_MS=30000
ENABLE_CACHING=false
LOG_LEVEL=INFO
# Rate Limiting
RATE_LIMIT_REQUESTS_PER_MINUTE=100
RATE_LIMIT_WINDOW_MS=60000
API Key Setup
- Sign up for a CharityAPI account
- Generate an API key from your dashboard
- Add the API key to your
.envfile
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
2. Charity Search (charity_search)
Search for charities by name, location, or other criteria.
Input:
query(string, optional): Organization name or keywordscity(string, optional): Filter by city namestate(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
-
Charity Verification Guide (
charity_verification_guide)- Complete guide for performing charity legitimacy verification
- Customizable by organization type (name_only, ein_based, suspicious, etc.)
-
Basic Legitimacy Workflow (
basic_legitimacy_workflow)- Step-by-step workflows for different verification scenarios
- Parameters: verification_type, organization_name, ein, location
-
Red Flag Detection (
red_flag_detection)- Guidance for detecting and handling problematic charity statuses
- Handles revoked, conditional, and suspended organizations
-
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
-
Quick Verification Reference (
quick_verification_reference)- Fast lookup templates for common verification scenarios
- Customizable by user input type
-
Response Templates Quick (
response_templates_quick)- Quick response templates with status indicators (✅ ⚠️ ❌)
- Templates for verified, cannot_verify, and problems_found cases
-
Tool Selection Guide (
tool_selection_guide)- Decision tree for selecting the right MCP tool
- Scenario-specific guidance for different verification contexts
-
Common Keywords Reference (
common_keywords_reference)- Reference of keywords that trigger charity verification
- Intent recognition patterns for AI assistants
-
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"
}
}
}
Usage with MCP Clients
Claude Desktop
Add to your Claude Desktop configuration:
{
"mcpServers": {
"charity-server": {
"command": "node",
"args": ["path/to/charity-mcp-server/build/index.js"],
"env": {
"CHARITY_API_KEY": "your_api_key_here"
}
}
}
}
Other MCP Clients
The server implements the standard MCP protocol and works with any compatible client. Connect using stdio transport.
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:
- MCP Layer: Handles protocol communication and tool registration
- Validation Layer: Input sanitization and validation with Zod schemas
- Service Layer: External API communication with rate limiting
- Transform Layer: Data transformation and standardization
- 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
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - 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
/docsfolder - 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