@catlabtech/mycal-mcp-server

@catlabtech/mycal-mcp-server

MCP (Model Context Protocol) server exposing the Malaysia Calendar API as 12 ready-to-use tools for Claude, ChatGPT, and other AI agents.

Data sourced from the official Malaysian government gazette (JPM BKPP), JAKIM, KPM, and MPM.

Why

LLMs are notoriously bad at Malaysia-specific calendar questions:

• They get Islamic holidays wrong (incorrect Hijri → Gregorian mapping)
• They don't know about cuti peristiwa announced after their training cutoff
• They confuse state-specific vs federal holidays
• They default to Sat–Sun weekends — wrong for Kedah, Kelantan, Terengganu (Fri–Sat)

Drop this MCP server into your AI client and all those questions get answered from the live gazette-backed API instead of hallucinated.

Setup with Claude Desktop

Edit your Claude Desktop config:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Add (or merge into the existing mcpServers block):

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

Completely quit Claude Desktop and reopen. Test with:

"Is March 21, 2026 a public holiday in Selangor?" "What are the long weekends for KL in 2026?"

Setup with Claude Code

claude mcp add malaysia-calendar --scope user -- npx -y @catlabtech/mycal-mcp-server

Or commit to your repo's .mcp.json for team-wide setup. Verify with /mcp in a Claude Code session.

Available tools (12)

Tool	What it does
get_malaysia_holidays	List holidays (filter by year, state, type, status, month)
check_malaysia_holiday	Is this date a holiday, weekend, working day, or school day?
next_malaysia_holiday	Next N upcoming holidays
malaysia_business_days	Count working days in range, or add N business days to a date
malaysia_long_weekends	All 3+ day non-working stretches in the year
list_malaysia_states	16 states + 3 FTs with weekend config
resolve_malaysia_state	Alias (kl, jb, n9) → canonical code
malaysia_holiday_changes	Recent additions / changes — useful for cuti peristiwa tracking
malaysia_school_terms	KPM school term dates + school-day counts
malaysia_school_holidays	Cuti penggal, pertengahan, akhir, perayaan
malaysia_exams	SPM, STPM, MUET, PT3 schedules
malaysia_is_school_day	Is this date a school day for this state/group?

How it works

Your AI client                MyCal MCP server            Calendar API
(Claude, etc.)      ──────▶   (local npx process)  ────▶  (Cloudflare Workers)
            stdio JSON-RPC                           HTTPS

The server runs locally via npx. It speaks MCP over stdio on one side and HTTPS to the API on the other. Nothing to host yourself. No API key needed.

Troubleshooting

"Command not found: npx" — install Node 18+ from nodejs.org.

"Server disconnected" / MCP not responding — check node -v is ≥ 18. Older Node versions lack ESM/fetch features the server needs.

First call is slow — npx downloads the package on first use. Subsequent calls are fast.

Corporate network blocked — the server needs outbound HTTPS to mycal-api.huijun00100101.workers.dev.

Documentation

• Full guide: https://mycal-web.pages.dev/docs/mcp-server/what-is-mcp
• Tool reference: https://mycal-web.pages.dev/docs/mcp-server/tools

Related packages

• @catlabtech/mycal-sdk — TypeScript client SDK for direct REST usage
• @catlabtech/mycal-core — shared types and schemas

License

MIT — © catlab.tech

Issues and contributions: github.com/Junhui20/malaysia-calendar-api