Mycal

Malaysia Calendar API

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

[npm: mycal-core] [npm: mycal-sdk] [npm: mycal-mcp-server] [License: MIT] [Deploys on Cloudflare]

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

Links

• Website + demo: https://mycal-web.pages.dev
• Developer docs: https://mycal-web.pages.dev/docs
• API base URL: https://mycal-api.huijun00100101.workers.dev/v1
• GitHub: https://github.com/Junhui20/malaysia-calendar-api

Packages

Published to npm under the @catlabtech scope:

Features

• 50 public holidays for 2026 from official gazette (Warta Kerajaan) — federal + state-specific
• 13 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

# Clone and installgit clone https://github.com/Junhui20/malaysia-calendar-api.gitcd malaysia-calendar-apipnpm install
# Build shared packagespnpm --filter @catlabtech/mycal-core buildpnpm --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 datapnpm validate
# Run testspnpm test

API Examples

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

List holidays

# All holidays for Selangor in 2026curl "https://mycal-api.huijun00100101.workers.dev/v1/holidays?year=2026&state=selangor"
# Islamic holidays onlycurl "https://mycal-api.huijun00100101.workers.dev/v1/holidays?year=2026&type=islamic"
# March holidays for KLcurl "https://mycal-api.huijun00100101.workers.dev/v1/holidays?year=2026&state=KL&month=3"

Check a date

# 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:

{  "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

# Count working days in March for Selangorcurl "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 datecurl "https://mycal-api.huijun00100101.workers.dev/v1/business-days/add?date=2026-03-01&days=10&state=selangor"

School calendar

# 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 Bcurl "https://mycal-api.huijun00100101.workers.dev/v1/school/holidays?year=2026&group=B"
# Exam schedulecurl "https://mycal-api.huijun00100101.workers.dev/v1/school/exams?year=2026&type=spm"

Next holiday

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

State resolution

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

Full API Reference

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

SDK Usage

import { MyCalClient } from "@catlabtech/mycal-sdk";
const cal = new MyCalClient();
// Check if a date is a working dayconst result = await cal.check("2026-03-21", "selangor");console.log(result.isWorkingDay); // false
// List holidaysconst holidays = await cal.holidays({ year: 2026, state: "KL" });
// Business daysconst workDays = await cal.businessDays("2026-03-01", "2026-03-31", "selangor");console.log(workDays.businessDays); // 22
// School calendarconst 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:

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

Available Tools (13)

State Codes

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              # 13 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:

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

Deploy

Two parts deploy independently:

API → Cloudflare Workers

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

Website → Cloudflare Pages

pnpm --filter @catlabtech/mycal-core buildpnpm --filter @catlabtech/mycal-sdk buildpnpm --filter @mycal/web build
# Direct upload via wrangler (requires CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID)cd packages/webnpx wrangler pages deploy dist --project-name=mycal-web

First-time Pages setup:

1. Create a Pages project named mycal-web in the Cloudflare dashboard.
2. 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.
3. Required GitHub secrets: CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID.

CI/CD

GitHub Actions handles:

1. PR gate — Zod schema validation + cross-source checks on every PR
2. Deploy — On merge to main: build and deploy API to Workers + Web to Pages in parallel
3. Daily scrape — Government portal monitoring for updates
4. 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