jmesplana/ifrc-go-admin-mcp-server

IFRC GO Admin API MCP Server

A Model Context Protocol (MCP) server that provides access to the International Federation of Red Cross and Red Crescent Societies (IFRC) GO Admin API for disaster relief emergency fund (DREF) data.

Features

• DREF Operations: Access completed and ongoing disaster relief emergency fund operations
• Appeals: Query humanitarian funding appeals
• Emergencies: Get emergency event and disaster data
• Search & Filter: Search by country, disaster type, and other criteria
• Caching: Built-in response caching to reduce API load
• Pagination: Handle large datasets efficiently

Prerequisites

• Node.js 18.0.0 or higher
• npm or yarn package manager
• MCP-compatible client (Claude Desktop, etc.)

Installation

1. Install Dependencies

npm install

2. Build the Project

npm run build

3. Test the Server

npm start

Usage

Configure in Claude Desktop

Add to your Claude Desktop configuration file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "ifrc-go-admin": {
      "command": "node",
      "args": ["/path/to/your/ifrc-go-admin-mcp-server/dist/index.js"]
    }
  }
}

Available Tools

1. get_completed_drefs: Retrieve completed DREF operations
2. get_ongoing_drefs: Get currently active DREF operations
3. get_appeals: Access humanitarian appeals for funding
4. get_emergencies: Query emergency events and disasters
5. search_drefs_by_country: Find DREF operations by country ISO code
6. search_drefs_by_disaster_type: Search by disaster type (flood, earthquake, etc.)
7. get_dref_statistics: Get summary statistics about DREF operations

Example Queries for AI Assistants

• "Show me recent earthquake-related DREF operations"
• "What are the ongoing emergency appeals in Bangladesh?"
• "Compare funding amounts for cyclone vs flood disasters this year"
• "List all completed DREF operations in West Africa"

Development

Scripts

• npm run build - Compile TypeScript to JavaScript
• npm run dev - Watch mode for development
• npm start - Start the production server
• npm test - Test server startup

API Exploration

Before implementing, explore the API endpoints:

# Test basic connectivity
curl "https://goadmin.ifrc.org/api/v2/dref/?limit=1"

# Check completed DREFs
curl "https://goadmin.ifrc.org/api/v2/completed_dref/?limit=5"

# Search by country
curl "https://goadmin.ifrc.org/api/v2/dref/?country__iso=BD"

Adding New Endpoints

1. Update Types: Add TypeScript interfaces for new data structures
2. Extend API Client: Add methods to IFRCAPIClient class
3. Register Tools: Add tool definitions in ListToolsRequestSchema handler
4. Implement Handlers: Add case in CallToolRequestSchema handler

Pagination Best Practices

Following IFRC API documentation guidelines:

• Default limit is 50 records per page
• Maximum limit is 1000 records per page
• Stop pagination when returned records < limit
• Check for empty array [] to confirm no more data
• Use offset-based pagination with limit/offset parameters

Rate Limiting Considerations

The server includes basic caching (5-minute timeout) to be respectful of IFRC's infrastructure. For production use:

• Implement exponential backoff for retries
• Add request rate limiting
• Monitor API usage and respect any documented limits
• Consider using webhooks for real-time updates if available

Error Handling

The server includes comprehensive error handling:

• HTTP errors from the API
• Invalid parameters
• Network timeouts
• Cache management

Authentication

Currently, the IFRC GO Admin API appears to be publicly accessible. If authentication is required:

1. Add API key management to the IFRCAPIClient class
2. Include authentication headers in requests
3. Handle authentication errors appropriately

Data Schema Examples

DREF Operation

{
  "id": 12345,
  "title": "Bangladesh: Cyclone Mocha",
  "country": "Bangladesh", 
  "disaster_type": "Cyclone",
  "amount_requested": 500000,
  "amount_funded": 500000,
  "disaster_start_date": "2023-05-14",
  "status": "completed"
}

Emergency Event

{
  "id": 67890,
  "name": "Morocco Earthquake September 2023",
  "countries": ["Morocco"],
  "disaster_type": "Earthquake", 
  "num_affected": 300000,
  "disaster_start_date": "2023-09-08"
}

Project Structure

ifrc-go-admin-mcp-server/
├── src/
│   └── index.ts          # Main MCP server implementation
├── dist/                 # Compiled JavaScript output
├── package.json          # Project configuration
├── tsconfig.json         # TypeScript configuration
└── README.md             # This file

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

Humanitarian Use Guidelines

This server provides access to sensitive humanitarian data. Please:

• Use responsibly and respect the humanitarian context
• Don't overwhelm the IFRC API with excessive requests
• Consider data privacy when analyzing beneficiary information
• Contribute improvements back to the humanitarian community

Support

For issues related to:

• MCP Server: Open an issue in this repository
• IFRC GO API: Contact IFRC technical support
• Data Questions: Refer to IFRC GO documentation

License

MIT License - See LICENSE file for details.

Acknowledgments

• International Federation of Red Cross and Red Crescent Societies
• Model Context Protocol development team
• Open source humanitarian technology community