Calendarific MCP Server

A Model Context Protocol (MCP) server for holiday data, built with FastMCP and the MCP framework. This server provides holiday-related tools that can be used by AI assistants to retrieve public holidays for different countries and years using the Calendarific API.

Features

🎯 Core Functionality

• Global Holiday Data: Access public holidays for 230+ countries and regions
• Multi-Year Support: Retrieve holidays for any year (past, present, or future)
• Detailed Information: Get holiday names, dates, and additional metadata

🔌 Integration & Compatibility

• MCP Protocol: Native Model Context Protocol support for AI assistants
• FastMCP Framework: Built on modern, high-performance MCP implementation
• Cross-Platform: Works on Windows, macOS, and Linux

🌍 Data Coverage

• ISO Standard: Uses ISO 3166-1 alpha-2 country codes (US, GB, IL, etc.)
• Real-Time API: Always up-to-date holiday information via Calendarific API
• Error Handling: Robust error management for API issues and invalid inputs

Requirements

• Python 3.13+
• uv package manager
• Calendarific API key

Installation

Manual Installation

1. Clone this repository:

   git clone https://github.com/yourusername/calendarific-mcp-server.git
   cd calendarific-mcp-server

2. Install dependencies using uv:

   uv venv
   uv pip install -e .

3. Create a .env file in the project root with your Calendarific API key:

   CALENDARIFIC_API_KEY=your_api_key_here

Usage

Run the server:

python main.py

The server will start and connect via stdio transport for MCP communication.

Available Tools

get_public_holidays

Get a list of public holidays for a specific country and year.

Parameters:

• country (str): ISO 3166-1 alpha-2 country code (e.g., "US", "GB", "IL")
• year (int): Year to get holidays for

Returns:

• List of holidays in format: "YYYY-MM-DD: Holiday Name"

Example:

# Get US holidays for 2024
holidays = await get_public_holidays("US", 2024)
# Returns: ["2024-01-01: New Year's Day", "2024-07-04: Independence Day", ...]

API Key Setup

1. Sign up for a free account at Calendarific
2. Get your API key from the dashboard
3. Add it to your .env file as CALENDARIFIC_API_KEY

Supported Countries

The server supports all countries available in the Calendarific API. Use ISO 3166-1 alpha-2 country codes:

• US (United States)
• GB (United Kingdom)
• IL (Israel)
• CA (Canada)
• AU (Australia)
• And many more...

Error Handling

The server includes comprehensive error handling:

• Invalid API key errors
• Network connectivity issues
• Invalid country codes
• API rate limiting

License

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

Support

For issues and questions:

• Check the Calendarific API documentation
• Open an issue on GitHub
• Review the MCP documentation