Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Charity MCP Server verify if the American Red Cross is a tax-deductible charity"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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
Related MCP server: DataNexus MCP
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
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
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
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
Node.js 18+
npm or yarn
CharityAPI account and API key
Clone the repository
git clone <repository-url>
cd charity-mcp-serverInstall dependencies
npm installConfigure environment variables
cp .env.example .env
# Edit .env with your API key and configurationBuild the project
npm run buildStart the server
npm startCreate 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=60000Sign up for a CharityAPI account
Generate an API key from your dashboard
Add the API key to your .env file
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
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:
{
"query": "American Red Cross",
"state": "CA",
"limit": 10
}Returns:
List of matching organizations
Pagination information
Basic details (name, EIN, location, deductibility)
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
The server provides built-in prompts to help AI assistants perform charity verification effectively:
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 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
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"
}
}
}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"
}
}
}
}The server implements the standard MCP protocol and works with any compatible client. Connect using stdio transport.
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# 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 lintThe 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
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
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
Default rate limits:
100 requests per minute per tool
Configurable via environment variables
Automatic cleanup of expired tokens
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
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
This project is licensed under the MIT License - see the LICENSE file for details.
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
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"
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
Model Context Protocol for the standard
CharityAPI.org for nonprofit data access
The open source community for inspiration and contributions
Look up detailed information about a charity or nonprofit organization using their EIN (Employer Identification Number). This tool retrieves comprehensive information from the IRS database including: - Official organization name and location - Tax deductibility status and codes - Organization classification and activity codes - Current status with the IRS - Foundation type and ruling information
Use this tool when you need complete details about a specific charity.| Name | Required | Description | Default |
|---|---|---|---|
| ein | Yes | The charity's EIN (Tax ID) in format XX-XXXXXXX or XXXXXXXXX (e.g., '13-1837418' or '131837418') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the data source (IRS database) and lists the types of information retrieved, which adds useful context. However, it does not mention behavioral aspects like rate limits, authentication needs, error handling, or whether the lookup is cached, leaving gaps in transparency for a tool with no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded: the first sentence states the core purpose, followed by a bulleted list of retrieved information for clarity, and ends with usage guidance. Every sentence earns its place without redundancy, making it efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (single parameter, no output schema, no annotations), the description is moderately complete. It explains what the tool does and what information it retrieves, but lacks details on output format, error cases, or integration with sibling tools. This is adequate but has clear gaps for a tool without annotations or output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, clearly documenting the 'ein' parameter with format and examples. The description adds no additional parameter semantics beyond what the schema provides, such as explaining EIN significance or validation rules. This meets the baseline of 3 since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Look up detailed information') and resource ('charity or nonprofit organization'), distinguishing it from siblings like 'charity-search' (likely broader search) and 'list-organizations' (likely listing multiple). It specifies using EIN as the identifier, making the purpose explicit and differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use it ('when you need complete details about a specific charity'), but does not explicitly state when not to use it or name alternatives among the sibling tools. This gives adequate guidance but lacks explicit exclusions or comparisons to other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for charities and nonprofit organizations in the IRS database. You can search by organization name, location, or combine multiple criteria.
Search parameters:
- query: Organization name or keywords
- city: Filter by city name
- state: Filter by state (2-letter code like 'CA', 'NY')
Returns a list of matching organizations with basic information including:
- Organization name and EIN
- Location (city, state)
- Deductibility status
Use this tool to find organizations when you don't have their exact EIN.| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Search term for organization name or keywords | |
| city | No | Filter by city name (optional) | |
| state | No | Filter by state using 2-letter abbreviation like 'CA' or 'NY' (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses the tool's purpose (search) and return format (list with basic information), but lacks details about behavioral traits like rate limits, authentication requirements, pagination, or error conditions. The description doesn't contradict any annotations since none exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured with clear sections: purpose statement, search parameters explanation, return format description, and usage guidance. Every sentence adds value without redundancy, and the information is front-loaded appropriately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (search with optional filters) and 100% schema coverage but no output schema, the description provides good context about what the tool does and returns. However, without an output schema, the description should ideally provide more detail about the return structure beyond just listing field names.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters thoroughly. The description adds minimal value by listing parameters in bullet form and clarifying that city and state are filters, but doesn't provide additional semantic context beyond what's in the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Search for charities and nonprofit organizations'), resource ('IRS database'), and scope ('by organization name, location, or combine multiple criteria'). It distinguishes from sibling tools by focusing on search functionality rather than lookup, listing, or checking operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool ('when you don't have their exact EIN'), which implicitly suggests charity-lookup might be for exact EIN searches. However, it doesn't explicitly state when NOT to use it or name specific alternatives among the siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List nonprofit organizations from the IRS database that have been updated since a specified date. This tool retrieves organizations that have had changes to their tax-exempt status or filing information.
Parameters:
- since: ISO date string (required) - Get organizations updated since this date (e.g., "2024-01-01T00:00:00Z")
Returns detailed information about organizations including:
- Basic information (EIN, name, address)
- Tax status and classification details
- Financial information (revenue, assets)
- Filing requirements and ruling dates
Use this tool to get bulk organization data or track recent changes to nonprofit status.| Name | Required | Description | Default |
|---|---|---|---|
| since | Yes | ISO date string to get organizations updated since this date (e.g., '2024-01-01T00:00:00Z') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses the tool retrieves organizations with changes to tax-exempt status or filing information, which adds behavioral context. However, it doesn't mention important behavioral aspects like pagination, rate limits, authentication requirements, or what constitutes 'updated' (metadata changes vs. substantive changes).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections: purpose, parameters, return values, and usage guidance. It's appropriately sized for a single-parameter tool. Minor improvement could be made by front-loading the most critical information more aggressively, but overall it's efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read operation with no output schema, the description provides adequate context about what data is returned. However, without annotations and with no output schema, it should ideally provide more detail about response format, pagination, or limitations. The description compensates somewhat by listing return data categories but doesn't fully address the lack of structured output information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents the single 'since' parameter. The description repeats the parameter information but doesn't add meaningful semantic context beyond what's in the schema. The baseline of 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and resource 'nonprofit organizations from the IRS database' with specific scope 'updated since a specified date'. It distinguishes from siblings by specifying this is for bulk organization data or tracking recent changes, unlike lookup/search/check tools that likely focus on individual organizations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: 'to get bulk organization data or track recent changes to nonprofit status'. However, it doesn't explicitly state when NOT to use it or name specific alternatives among the sibling tools (charity-lookup, charity-search, public-charity-check).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verify if a nonprofit organization qualifies as a "public charity" according to the IRS. Public charities are eligible to receive tax-deductible donations under section 501(c)(3).
This tool returns:
- Whether the organization is classified as a public charity
- Tax deductibility status for donations
- EIN confirmation
Use this tool to quickly verify if donations to an organization are tax-deductible.| Name | Required | Description | Default |
|---|---|---|---|
| ein | Yes | The charity's EIN (Tax ID) in format XX-XXXXXXX or XXXXXXXXX (e.g., '13-1837418' or '131837418') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does disclose key behavioral traits: it's a verification/checking tool (not a mutation), returns specific information (public charity status, tax deductibility, EIN confirmation), and mentions the IRS context. However, it doesn't cover potential limitations like rate limits, error conditions, or data freshness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized with four sentences that each serve a purpose: defines the tool's purpose, provides IRS context, lists return values, and gives usage guidance. It's front-loaded with the core purpose, though the structure could be slightly more streamlined.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter verification tool with no output schema, the description provides good contextual completeness: it explains what the tool does, what it returns, and when to use it. The main gap is the lack of output format details, but given the tool's relative simplicity, this is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single 'ein' parameter, so the schema already fully documents the parameter format and requirements. The description doesn't add any meaningful parameter semantics beyond what's in the schema, maintaining the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('verify', 'qualifies') and resource ('nonprofit organization'), and distinguishes it from siblings by focusing on IRS public charity status verification rather than general lookup/search/list operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool ('to quickly verify if donations to an organization are tax-deductible'), but doesn't explicitly mention when NOT to use it or name specific alternatives among the sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
charity-lookupcharity-searchlist-organizationspublic-charity-checkScored across 4 tools
Each tool has a clearly distinct purpose with no overlap: charity-lookup retrieves detailed info by EIN, charity-search finds charities by criteria, list-organizations lists updated organizations by date, and public-charity-check verifies public charity status. The descriptions explicitly differentiate use cases, preventing misselection.
Three tools follow a consistent 'charity-' or 'list-' prefix pattern (charity-lookup, charity-search, public-charity-check, list-organizations), but 'public-charity-check' deviates slightly by including a hyphenated adjective. The naming is mostly predictable and readable, with only minor inconsistency in the prefix style.
With 4 tools, the server is well-scoped for its charity/nonprofit domain. Each tool serves a specific function (lookup, search, listing, verification) that earns its place, avoiding bloat or thin coverage. This count is appropriate for the apparent scope of IRS database interactions.
The tool set covers core operations for charity information retrieval: lookup by EIN, search by criteria, bulk listing by date, and status verification. Minor gaps exist, such as no explicit tools for updating or managing data (e.g., CRUD operations), but agents can work around this given the server's likely read-only focus on IRS data.
Search, verify and compare 7.9M+ nonprofits from official charity registries in 100+ countries.
Nonprofit lookup and IRS 990 filing data: revenue, assets, and compensation via ProPublica
MCP server for nonprofit financials via ProPublica ā IRS Form 990 data for 1.8M+ nonprofits.
ProPublica Nonprofit MCP ā ProPublica Nonprofit Explorer API (free, no auth)
