PH Holidays MCP Server

A Model Context Protocol server that provides Philippine national holiday data to LLMs. Built on Cloudflare Workers with KV storage.

Public, read-only, no authentication required. Data sourced from official presidential proclamations published in the Official Gazette. Cached in Cloudflare KV for reliability and low-latency global access.

Tools

| Tool | Description | |------|-------------| | get_holidays | Get all holidays for a given year, optionally filtered by type | | get_holiday_by_date | Look up whether a specific date is a holiday | | get_upcoming_holidays | Get the next N holidays from a given date | | is_working_day | Check if a specific date is a working day per proclamation data | | get_long_weekends | Get all long weekend windows for a year |

Holiday Types

| Type | Value | Pay Behavior | |------|-------|--------------| | Regular Holiday | regular | 200% if worked, 260% on rest day | | Special Non-Working | special_non_working | No work, no pay. 130% if worked | | Special Working | special_working | Ordinary working day. No premium | | Islamic Holiday | islamic | Same rules as regular. Separate proclamation. |

Pay rules are informational metadata only. This server does not compute pay.

Response Format

All data responses are wrapped in a standard envelope:

{
  "_meta": {
    "year": 2026,
    "tier": "current",
    "proclamation": "No. 1006",
    "eid_fitr_status": "pending",
    "eid_adha_status": "pending",
    "last_updated": "2026-03-08",
    "source": "Official Gazette of the Republic of the Philippines"
  },
  "data": { ... }
}

Error responses (isError: true) are returned as plain text without wrapping.

Holiday Record

| Field | Type | Description | |-------|------|-------------| | date | string | ISO 8601 date: YYYY-MM-DD | | name | string | Official holiday name | | type | string | regular, special_non_working, special_working, islamic | | day_of_week | string | Full day name (e.g. "Thursday") | | movable | boolean | Whether the date is defined by a day-of-week rule | | double_holiday | boolean | Whether two holidays share this date | | double_holiday_names | string[] \| null | Names of both holidays when double | | long_weekend | object | Long weekend window info (see below) | | source | object | Proclamation reference | | notes | string \| null | Additional context |

All fields are always present. Fields without data are null, never omitted.

Islamic Holiday Record

Islamic holidays include additional fields:

| Field | Type | Description | |-------|------|-------------| | eid_confirmed | boolean | Whether the date has been confirmed by NCMF | | estimated_date | string | Astronomical estimate before confirmation | | confirmed_date | string \| null | Actual proclaimed date after confirmation | | proclamation_ref | string \| null | Separate proclamation number |

Long Weekend Window

| Field | Type | Description | |-------|------|-------------| | is_part_of | boolean | Whether this holiday is part of a long weekend | | window_start | string \| null | First date of the window | | window_end | string \| null | Last date of the window | | days | number | Total days in the window | | leave_days_needed | number | Bridge leave days required (0 = natural) | | dates | string[] | All dates in the window |

is_working_day Response

{
  "_meta": { ... },
  "data": {
    "date": "2026-02-25",
    "is_working_day": true,
    "reason": "Special Working Day: EDSA People Power Revolution Anniversary",
    "holiday_type": "special_working"
  }
}

Connect

Add to your MCP client configuration:

{
  "mcpServers": {
    "ph-holidays": {
      "url": "https://ph-holidays.godmode.ph/mcp"
    }
  }
}

Quick test

curl -X POST https://ph-holidays.godmode.ph/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_upcoming_holidays",
      "arguments": { "limit": 3 }
    }
  }'

Quirks

1. Islamic holidays have a 2-phase lifecycle. Eid'l Fitr and Eid'l Adha appear in the main proclamation as "to be proclaimed." Dates are confirmed later via separate proclamations after NCMF recommendation. The eid_fitr_status and eid_adha_status fields in _meta signal "pending" or "confirmed". When pending, estimated_date is included but is not authoritative.

2. Special working days are counterintuitive. The EDSA People Power Anniversary (Feb 25, 2026) appears in the proclamation but is a working day with no premium. is_working_day returns true. holiday_type returns "special_working". Example:

   is_working_day("2026-02-25") -> true, reason: "Special Working Day: EDSA..."

3. is_working_day does not account for weekends. Checks proclamation data only. Saturday/Sunday handling is the caller's responsibility. Rest day schedules vary by employer and are outside this server's scope.

4. Double holidays are rare but flagged. When 2 holidays fall on the same date, double_holiday: true is set on the record. Pay stacking rules apply but computation is not handled by this server.

5. Pending Eid dates should not be used for hard scheduling. When eid_confirmed is false, estimated_date is based on astronomical estimates. The actual proclaimed date may differ by 1 day.

6. Local holidays are out of scope. City-level holidays (Quezon City Day, Manila Day, Cebu City Charter Day, etc.) are not included. Reserved for v2 integration via psgc-mcp cross-reference.

7. next year data may not be available. The index only includes next year after the proclamation drops (typically October). get_upcoming_holidays crossing into the next year will stop at Dec 31 if next year is not yet loaded.

Data Sources

| Source | Used For | |--------|----------| | Official Gazette | Authoritative proclamation text | | Presidential Proclamations (Malacanan) | Annual holiday list | | DOLE Labor Advisories | Pay rule reference (informational) | | NCMF | Eid date confirmations |

Current year: 2026 (Proclamation No. 1006, signed September 3, 2025).

Year Coverage

| Tier | Years | Notes | |------|-------|-------| | current | 2026 | Actively maintained. Eid patched when confirmed. | | next | -- | Loaded in October when proclamation drops. |

At any given time, KV holds at most 2 years. No historical data.

Data Pipeline

scripts/
  data/
    2026/  proclamation-source.json
  seed.ts          -- full KV load for a given year
  rollover.ts      -- promote next to current, drop old current
  patch-eid.ts     -- targeted Eid date update
  patch-holiday.ts -- ad hoc single holiday patch
  validate.ts      -- schema validation before deploy

Seed a year

npm run seed -- --year=2026

Validate before deploy

npm run validate -- --year=2026

Patch Eid after NCMF confirmation

npm run patch-eid -- --year=2026 --holiday=fitr --date=2026-03-21 --proclamation="No. 1234"

Year rollover (January 1)

npm run rollover

Development

npm install
npm run seed -- --year=2026
npm run dev

Dev server starts at http://localhost:8787. Connect your MCP client to http://localhost:8787/mcp.

Setup

Before first deploy, create the KV namespace:

npx wrangler kv namespace create HOLIDAYS_KV

Update wrangler.jsonc with the returned namespace ID.

Related Projects

Part of a suite of Philippine public data MCP servers:

• PSGC MCP - Philippine Standard Geographic Code
• LTS MCP - DHSUD License to Sell verification
• PH Holidays MCP (this repo)
• BSP Bank Directory MCP -> Coming soon

All servers are free, public, and read-only. Data pulled from official Philippine government sources.

Contributing and Issues

Found a data error or a holiday that was missed? Open an issue. Philippine holidays can change via mid-year proclamations, and the issues list is the best place to flag them.

Eid dates are confirmed separately each year. When NCMF announces the confirmed date, open an issue or PR with the proclamation reference.

Built by

Aaron Zara - Fractional CTO at Godmode Digital

For enterprise SLAs, custom integrations, or other PH data sources: -> godmode.ph

License

MIT