Malaysia Calendar API

Malaysia's most complete calendar API — public holidays, school calendar, exam schedules, and MCP server for AI tools.

Data source: Official government gazette (JPM BKPP), JAKIM, KPM, MPM. Not scraped from third-party websites.

Packages

Published to npm under the @catlabtech scope:

Package	Purpose	Install
`@catlabtech/mycal-core`	Shared types, Zod schemas, and calendar/business-day logic	`npm install @catlabtech/mycal-core`
`@catlabtech/mycal-sdk`	TypeScript client SDK for the REST API	`npm install @catlabtech/mycal-sdk`
`@catlabtech/mycal-mcp-server`	MCP server exposing 13 calendar tools for AI agents	`npm install @catlabtech/mycal-mcp-server`

Features

49 public holidays for 2026 from official gazette (Warta Kerajaan) — federal + state-specific
16 states + 3 Federal Territories with aliases (KL, JB, Penang, etc.)
Weekend-aware — Kedah/Kelantan/Terengganu use Fri-Sat (Kumpulan A), all others use Sat-Sun (Kumpulan B), with Johor's historical switch tracked
Cuti ganti (replacement holiday) auto-calculation per state weekend config
Business day calculator — per-state, holiday-aware
School calendar — terms, holidays, KPM cuti perayaan (Lampiran A/B/C)
Exam schedules — SPM, STPM, MUET, PT3
iCal subscription feeds — per-state .ics feeds
MCP Server for AI agents — 13 tools for Claude, ChatGPT, and other assistants
TypeScript SDK (@catlabtech/mycal-sdk) with typed responses
OpenAPI 3.1 spec + interactive docs
Trilingual — Bahasa Melayu, English, Chinese names (三语支持)

Quick Start

bash

# Clone and install
git clone https://github.com/Junhui20/malaysia-calendar-api.git
cd malaysia-calendar-api
pnpm install

# Build shared packages
pnpm --filter @catlabtech/mycal-core build
pnpm --filter @catlabtech/mycal-sdk build

# Run API locally (http://localhost:8787)
cd packages/api && npx wrangler dev

# Run web site locally (http://localhost:4321)
pnpm --filter @mycal/web dev

# Validate data
pnpm validate

# Run tests
pnpm test

API Examples

Base URL: https://mycal-api.huijun00100101.workers.dev/v1

List holidays

bash

# All holidays for Selangor in 2026
curl "https://mycal-api.huijun00100101.workers.dev/v1/holidays?year=2026&state=selangor"

# Islamic holidays only
curl "https://mycal-api.huijun00100101.workers.dev/v1/holidays?year=2026&type=islamic"

# March holidays for KL
curl "https://mycal-api.huijun00100101.workers.dev/v1/holidays?year=2026&state=KL&month=3"

Check a date

bash

# Is March 21 a holiday/weekend/working day?
curl "https://mycal-api.huijun00100101.workers.dev/v1/holidays/check?date=2026-03-21&state=KL"

Response:

json

{
  "data": {
    "date": "2026-03-21",
    "dayOfWeek": "Saturday",
    "isHoliday": true,
    "isWeekend": true,
    "isWorkingDay": false,
    "isSchoolDay": false,
    "holidays": [
      {
        "id": "2026-hari-raya-aidilfitri-1",
        "name": { "ms": "Hari Raya Aidilfitri", "en": "Eid al-Fitr", "zh": "开斋节" },
        "type": "islamic",
        "status": "confirmed"
      }
    ]
  }
}

Business days

bash

# Count working days in March for Selangor
curl "https://mycal-api.huijun00100101.workers.dev/v1/business-days?start=2026-03-01&end=2026-03-31&state=selangor"

# Add 10 business days to a date
curl "https://mycal-api.huijun00100101.workers.dev/v1/business-days/add?date=2026-03-01&days=10&state=selangor"

School calendar

bash

# Is this a school day?
curl "https://mycal-api.huijun00100101.workers.dev/v1/school/is-school-day?date=2026-03-21&state=selangor"

# School holidays for Kumpulan B
curl "https://mycal-api.huijun00100101.workers.dev/v1/school/holidays?year=2026&group=B"

# Exam schedule
curl "https://mycal-api.huijun00100101.workers.dev/v1/school/exams?year=2026&type=spm"

Next holiday

bash

# Next holiday for Penang
curl "https://mycal-api.huijun00100101.workers.dev/v1/holidays/next?state=penang"

State resolution

bash

# Resolve alias
curl "https://mycal-api.huijun00100101.workers.dev/v1/states/resolve?q=kl"
# -> { "data": { "canonical": "kuala-lumpur", "group": "B" } }

Full API Reference

Endpoint	Description
`GET /v1/holidays`	List holidays (filter by year, state, type, status, month)
`GET /v1/holidays/check`	Is this date a holiday/weekend/working day/school day?
`GET /v1/holidays/today`	Today's holiday status
`GET /v1/holidays/next`	Next upcoming holiday
`GET /v1/holidays/between`	Holidays in date range
`GET /v1/holidays/leave-optimizer`	Suggest annual-leave days to spend for the longest consecutive break
`GET /v1/business-days`	Count business days between dates
`GET /v1/business-days/add`	Add N business days to a date
`GET /v1/states`	All 16 states + 3 FTs with weekend config
`GET /v1/states/resolve`	Resolve alias (KL, penang, jb) to canonical code
`GET /v1/school/terms`	School term dates + day counts
`GET /v1/school/holidays`	School holidays + KPM cuti perayaan
`GET /v1/school/exams`	SPM, STPM, MUET, PT3 schedule
`GET /v1/school/is-school-day`	Is this a school day?
`GET /v1/feed/ical/:state`	iCal subscription feed
`GET /v1/feed/csv/:state`	CSV/spreadsheet export of holidays
`GET /v1/data/*`	Raw, cacheable open-data snapshots — `manifest`, `states`, `holidays/:year`, `all` (no API key required)
`GET /v1/prayer-times/:zone`	JAKIM prayer times for a zone (MYT-formatted); `GET /v1/prayer-times/zones` lists the zone directory
`POST /v1/keys`	Issue an API key (admin-gated for now; `GET /v1/keys/whoami` checks the caller's tier)

See the full OpenAPI 3.1 spec for request/response schemas.

SDK Usage

typescript

import { MyCalClient } from "@catlabtech/mycal-sdk";

const cal = new MyCalClient();

// Check if a date is a working day
const result = await cal.check("2026-03-21", "selangor");
console.log(result.isWorkingDay); // false

// List holidays
const holidays = await cal.holidays({ year: 2026, state: "KL" });

// Business days
const workDays = await cal.businessDays("2026-03-01", "2026-03-31", "selangor");
console.log(workDays.businessDays); // 22

// School calendar
const terms = await cal.school.terms({ year: 2026, group: "B" });
const exams = await cal.school.exams({ year: 2026, type: "spm" });
const isSchool = await cal.school.isSchoolDay("2026-03-21", "selangor");

MCP Server

Connect the Malaysia Calendar API to Claude, ChatGPT, or any MCP-compatible AI assistant.

Setup with Claude Desktop / Claude Code

Add to your MCP configuration:

json

{
  "mcpServers": {
    "malaysia-calendar": {
      "command": "npx",
      "args": ["@catlabtech/mycal-mcp-server"]
    }
  }
}

Available Tools (13)

Tool	Description
`get_malaysia_holidays`	Get public holidays (filter by year, state, type)
`check_malaysia_holiday`	Check if a date is a holiday or working day
`next_malaysia_holiday`	Find the next upcoming holiday
`malaysia_business_days`	Count working days between two dates
`malaysia_long_weekends`	Find long weekends (3+ days)
`malaysia_leave_optimizer`	Find the most efficient leave days to take to maximise consecutive days off
`list_malaysia_states`	List all states with weekend config
`resolve_malaysia_state`	Resolve alias (KL, JB) to canonical code
`malaysia_holiday_changes`	Recent data changes
`malaysia_school_terms`	School term dates and day counts
`malaysia_school_holidays`	School holidays (cuti penggal, cuti perayaan)
`malaysia_exams`	SPM, STPM, MUET, PT3 exam schedule
`malaysia_is_school_day`	Check if a date is a school day

State Codes

Code	Aliases	Group	Weekend
`johor`	jhr, jb	B	Sat-Sun (was Fri-Sat 2014-2024)
`kedah`	kd, kdh	A	Fri-Sat
`kelantan`	kel, kb	A	Fri-Sat
`terengganu`	trg, kt	A	Fri-Sat
`perak`	prk, ipoh	B	Sat-Sun
`pulau-pinang`	penang, pg	B	Sat-Sun
`selangor`	sel, sgr	B	Sat-Sun
`negeri-sembilan`	ns, n9	B	Sat-Sun
`melaka`	mlk, malacca	B	Sat-Sun
`pahang`	phg, kuantan	B	Sat-Sun
`perlis`	pls, kangar	B	Sat-Sun
`sabah`	sbh, kk	B	Sat-Sun
`sarawak`	swk, kuching	B	Sat-Sun
`kuala-lumpur`	kl	B	Sat-Sun
`wp-putrajaya`	putrajaya, pjy	B	Sat-Sun
`wp-labuan`	labuan, lbn	B	Sat-Sun

State aliases are case-insensitive. Use GET /v1/states/resolve?q=kl to resolve any alias to the canonical code.

Project Structure

malaysia-calendar-api/
├── data/                        # JSON data files (source of truth / 数据源)
│   ├── holidays/
│   │   ├── 2024.json            # Holiday data per year
│   │   ├── 2025.json
│   │   └── 2026.json
│   ├── school/
│   │   ├── terms-2026.json      # School terms (Kumpulan A + B)
│   │   ├── holidays-2026.json   # School holidays + KPM cuti perayaan
│   │   └── exams-2026.json      # SPM, STPM, MUET, PT3 schedules
│   ├── states.json              # 16 states + 3 FT, aliases, weekend history
│   └── known-fixed-holidays.json
├── packages/
│   ├── core/                    # Shared business logic (types, schemas, utils)
│   │   └── src/
│   │       ├── types.ts         # Holiday, State, SchoolTerm, Exam interfaces
│   │       ├── schemas.ts       # Zod validation schemas
│   │       ├── filter.ts        # Query filtering logic
│   │       ├── replacement.ts   # Cuti ganti calculation
│   │       ├── state-resolver.ts
│   │       ├── business-days.ts
│   │       └── school.ts        # School term/holiday/exam logic
│   ├── api/                     # Hono API on Cloudflare Workers
│   ├── mcp-server/              # MCP Server (13 tools)
│   ├── sdk/                     # TypeScript client SDK (@catlabtech/mycal-sdk)
│   └── web/                     # Astro + Starlight — marketing site, demos, docs
├── scripts/
│   ├── validate-data.ts         # 5-layer data validation pipeline
│   └── sync-to-kv.ts           # JSON -> Cloudflare KV denormalization
├── openapi.yaml                 # OpenAPI 3.1 spec (spec-first)
├── pnpm-workspace.yaml
└── turbo.json

Data Sources

All data is sourced from official Malaysian government publications:

Source	Data	URL
JPM BKPP	Federal Gazette / Warta Kerajaan (public holidays)	kabinet.gov.my
JAKIM	Takwim Hijri-Miladi (Islamic calendar)	e-solat.gov.my
KPM	Kalendar Akademik / school calendar (Lampiran A/B/C)	moe.gov.my
MPM	STPM & MUET exam schedules	mpm.edu.my
State Portals	State-specific holidays (16 states)	*.gov.my

Holiday data includes gazette references (e.g., P.U.(B) 305/2025) for traceability.

Deploy

Two parts deploy independently:

API → Cloudflare Workers

bash

pnpm --filter @catlabtech/mycal-core build
cd packages/api && npx wrangler deploy

Website → Cloudflare Pages

bash

pnpm --filter @catlabtech/mycal-core build
pnpm --filter @catlabtech/mycal-sdk build
pnpm --filter @mycal/web build

# Direct upload via wrangler (requires CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID)
cd packages/web
npx wrangler pages deploy dist --project-name=mycal-web

First-time Pages setup:

Create a Pages project named mycal-web in the Cloudflare dashboard.
Either connect the GitHub repo for automatic builds, or rely on the GitHub Actions workflow (.github/workflows/deploy.yml) to push via wrangler pages deploy.
Required GitHub secrets: CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID.

CI/CD

GitHub Actions handles:

PR gate — Zod schema validation + cross-source checks on every PR
Deploy — On merge to main: build and deploy API to Workers + Web to Pages in parallel
Daily scrape — Government portal monitoring for updates
Rukyah monitor — Islamic date confirmation tracking

Contributing

See CONTRIBUTING.md for how to:

Report a missing holiday or cuti peristiwa
Fix data errors
Add new features

License

MIT

Mycal

What it does

What it costs

Malaysia Calendar API

Links

Packages

Features

Quick Start

API Examples

List holidays

Check a date

Business days

School calendar

Next holiday

State resolution

Full API Reference

SDK Usage

MCP Server

Setup with Claude Desktop / Claude Code

Available Tools (13)

State Codes

Project Structure

Data Sources

Deploy

API → Cloudflare Workers

Website → Cloudflare Pages

CI/CD

Contributing

License

Similar modules