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

Holiday Types

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

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

Islamic Holiday Record

Islamic holidays include additional fields:

Long Weekend 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-mcp.godmodearch.workers.dev/mcp"
    }
  }
}

Quick test

curl -X POST https://ph-holidays-mcp.godmodearch.workers.dev/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

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

Year Coverage

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