calendarific-mcp-server

noalimoy/calendarific-mcp-server

3.1

If you are the rightful owner of calendarific-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Calendarific MCP Server is a Model Context Protocol server designed to provide holiday data using the Calendarific API, enabling AI assistants to access public holidays for various countries and years.

Tools
1
Resources
0
Prompts
0

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

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 file for details.

Support

For issues and questions: