Taiwan Holiday MCP Server
This MCP server lets AI clients query Taiwan holiday, workday, and related calendar information through standardized tools.
Check whether a specific date is a Taiwan holiday using
YYYY-MM-DDorYYYYMMDD.List all holidays within a start/end date range.
Get holiday statistics for a year or a specific year-month.
Get the next N holidays after a date, with optional weekend skipping and data-truncation metadata.
Calculate workdays for a full month or date range, excluding weekends/holidays and separately reporting makeup workdays.
The README also describes typhoon-closure lookup, but the provided server schema does not include that tool.
Utilizes GitHub as a data source for Taiwan holiday information through the TaiwanCalendar repository.
Uses jsDelivr's CDN to fetch Taiwan holiday data from the TaiwanCalendar GitHub repository.
Provides cross-platform support including Linux systems.
Supports macOS with specific configuration file paths for Claude Desktop integration.
Built on Node.js runtime, requiring version 18+ for proper functionality.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Taiwan Holiday MCP Server what holidays are there in October 2025?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Taiwan Holiday MCP Server
一個基於 Model Context Protocol (MCP) 的台灣假期查詢伺服器,提供準確的台灣國定假日和補班日資訊,以及颱風假(天然災害停止上班上課)查詢。
✨ 特色功能
🇹🇼 準確的台灣假期資料:基於 TaiwanCalendar 提供的政府公告假期資訊
🚀 即時查詢:支援單日查詢、範圍查詢、接下來的假期、工作天(含補班日)與統計查詢
🌀 颱風假查詢:今天、明天讀人事行政總處即時頁,其他日期讀 2001-07-30 起的歸檔
📅 多種日期格式:支援
YYYY-MM-DD和YYYYMMDD格式🔄 智慧快取:自動快取資料,提升查詢效能
🛠️ MCP 標準:完全相容 Model Context Protocol 規範
🎯 AI 友善:專為 Claude Desktop、Cursor 等 AI 工具設計
📊 豐富統計:提供假期統計和分析功能
🌐 跨平台:支援 Windows、macOS 和 Linux
Related MCP server: 12306-MCP
🚀 快速開始
NPX 直接使用(推薦)
最簡單的使用方式,無需安裝:
npx taiwan-holiday-mcp本地安裝
npm install -g taiwan-holiday-mcp
taiwan-holiday-mcp開發環境安裝
git clone https://github.com/lis186/taiwan-holiday-mcp.git
cd taiwan-holiday-mcp
npm install
npm run build
npm start🔧 客戶端設定
Claude Desktop 設定
在 Claude Desktop 的設定檔中新增:
{
"mcpServers": {
"taiwan-holiday": {
"command": "npx",
"args": ["taiwan-holiday-mcp"]
}
}
}設定檔位置:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
Cursor 設定
點擊以下按鈕直接安裝。
Windsurf 設定
在專案的 .cursorrules 或設定檔中新增:
{
"mcp": {
"servers": {
"taiwan-holiday": {
"command": "npx",
"args": ["taiwan-holiday-mcp"]
}
}
}
}📖 使用範例
安裝完成後,你可以直接在 Claude Desktop 中用自然語言與 AI 對話,詢問台灣假期相關問題:
基本查詢
你可以這樣問:
"2025年10月10日是假期嗎?"
"幫我查一下2025年1月有哪些假期"
"2025年總共有多少個假期?"
Claude 會自動呼叫相應的工具並回答:
✅ 2025年10月10日是國慶日,是假期
📅 2025年1月共有14個假期,包含春節連假
📊 2025年總共有115個假期
實用對話範例
🏖️ 假期規劃
你: "我想規劃2025年第一季的旅遊,幫我找出有哪些連假可以安排?"
Claude: 會自動查詢1-3月的假期,分析連續假期,並告訴你:
春節連假:1月27日-31日(5天)
228連假:2月28日-3月2日(3天)
其他週末假期安排建議
💼 工作安排
你: "下週一(2025年10月6日)需要上班嗎?"
Claude: 會檢查該日期並回答是否為工作日,如果是假期還會說明原因。
📈 假期統計
你: "2025年10月份有幾個假期?有什麼重要節日嗎?"
Claude: 會提供該月份的假期統計,包含國定假日和重要節慶資訊。
🌀 颱風假
你: "颱風要來了,明天臺北市要上班嗎?"
Claude: 會查詢明天臺北市的停班停課公告並回答:
已公告停止上班上課時,說明時段(全天、下午、幾點起)
只有部分區域或學制停止時,列出受影響的區域
人事行政總處尚未公告時,說明「目前無法確認」,不會當成照常上班,並提醒以縣市政府公告為準
進階應用
🎯 智慧假期分析
你: "幫我分析2025年哪個月份最適合請假旅遊?"
Claude: 會分析各月份的假期分布,考慮連假長度和頻率,給出最佳建議。
📅 年度假期規劃
你: "我想看2025年所有的長假期,幫我整理一個清單"
Claude: 會自動找出所有3天以上的連假,並按時間順序整理成清單。
🛠️ API 文件
MCP 工具
check_holiday
檢查指定日期是否為台灣假期。
參數:
date(string): 日期,格式為YYYY-MM-DD或YYYYMMDD
回傳:
{
"success": true,
"data": {
"date": "2025-10-10",
"isHoliday": true,
"description": "國慶日",
"week": "五",
"normalizedDate": "20251010"
}
}get_holidays_in_range
獲取指定日期範圍內的所有台灣假期。
參數:
start_date(string): 開始日期end_date(string): 結束日期
回傳:
{
"success": true,
"data": {
"startDate": "2025-01-01",
"endDate": "2025-01-31",
"holidays": [...],
"totalCount": 14,
"summary": "在 2025-01-01 到 2025-01-31 期間共有 14 個假期"
}
}get_holiday_stats
獲取指定年份或年月的台灣假期統計資訊。
參數:
year(number): 年份,2017 年起(實際可查年份由上游資料決定)month(number, 可選): 月份 (1-12)
回傳:
{
"success": true,
"data": {
"year": 2025,
"statistics": {
"year": 2025,
"totalHolidays": 115,
"nationalHolidays": 113,
"compensatoryDays": 2,
"holidayTypes": {...}
},
"summary": "2025 年共有 115 個假期"
}
}get_next_holidays
取得起算日之後的接下來 N 個台灣假期。語意對齊 taiwan-holiday-cli 的 holiday next:起算日當天即使放假也不算,搜尋範圍是起算日後 365 天(且不超過上游已發布的最後一年)。
參數:
date(string, 可選): 起算日,YYYY-MM-DD或YYYYMMDD。省略時為台北時區的今天count(integer, 可選): 要取得的數量,預設1,最大366skip_weekends(boolean, 可選): 略過一般週末(週六日且說明為空或「週末」),仍保留落在週末的具名假日。預設false
回傳:
{
"success": true,
"data": {
"found": true,
"count": 2,
"fromDate": "2026-01-01",
"searchedThrough": "2026-12-31",
"truncatedByData": false,
"holidays": [
{ "date": "2026-01-03", "week": "六", "description": "週末" },
{ "date": "2026-01-04", "week": "日", "description": "週末" }
]
},
"tool": "get_next_holidays"
}searchedThrough 是這次實際搜到的最後一天。truncatedByData 為 true 時,365 天視窗被上游最後一個已發布年度截斷,回傳筆數少於 count 不代表後面沒有假期。
找不到、而且搜尋窗裡真的沒有假期時,found 為 false、holidays 為 [],並帶 message: "查無假期"。起算日晚於已發布資料時,訊息改為 上游最新資料只到 N 年。一般週末的空說明會顯示為「週末」。補班日不是假期,不會出現在這份清單。
get_workdays
計算工作天數。可查整月,或查一段日期(含起迄日)。請擇一,不要同時指定。語意對齊 CLI 的 holiday workdays 與 holiday between:
週末與
isHoliday: true的日子計入holidays,不計入workdaysworkdays = totalDays - holidays補班日(說明含「補行上班」)不是假期,因此算工作天;
makeupWorkdays是這些日子的筆數,makeupWorkdayDates列出日期
整月參數:
year(integer): 年份month(integer): 月份 1-12
區間參數:
start_date(string): 起日,YYYY-MM-DD或YYYYMMDDend_date(string): 迄日,同一格式
整月回傳:
{
"success": true,
"data": {
"year": 2024,
"month": 1,
"totalDays": 31,
"workdays": 22,
"holidays": 9,
"makeupWorkdays": 1,
"makeupWorkdayDates": [
{ "date": "2024-01-06", "week": "六", "description": "補行上班" }
]
},
"tool": "get_workdays"
}區間回傳:
{
"success": true,
"data": {
"startDate": "2024-01-06",
"endDate": "2024-01-07",
"totalDays": 2,
"workdays": 1,
"holidays": 1,
"makeupWorkdays": 1,
"makeupWorkdayDates": [
{ "date": "2024-01-06", "week": "六", "description": "補行上班" }
]
},
"tool": "get_workdays"
}totalDays 在整月查詢是該月的日曆天數(閏年二月為 29)。上游該範圍的筆數必須剛好等於日曆天數;少一天或多一天都會回錯誤(例如 上游 2024 年 2 月 資料不完整(預期 29 筆,實得 2 筆)),不會把缺的日子當成工作天。
check_typhoon_closure
查詢颱風假(天然災害停止上班上課)。判斷規則與即時頁解析由 taiwan-holiday-cli 提供,
欄位語意見該專案 README 的「颱風假查詢」一節。
資料來源: 今天、明天讀 DGPA 天然災害停止上班及上課情形 即時頁; 其他日期讀 TaiwanTyphoonDays 歸檔(2001-07-30 起)。
參數:
date(string, 可選):today、tomorrow、YYYY-MM-DD或YYYYMMDD,省略為今天(臺灣時間)city(string, 可選): 縣市名稱,台/臺視為相同;省略為全國
回傳: summary 為一行結論,data 為完整的 TyphoonQueryResult。
{
"success": true,
"summary": "2024-10-31 臺北市:停止上班(全天)、停止上課(全天)〔已定案〕",
"data": {
"date": "20241031",
"city": "臺北市",
"work": { "status": "stopped", "period": "allDay", "from": "" },
"school": { "status": "stopped", "period": "allDay", "from": "" },
"basis": "own",
"reason": null,
"source": {...},
"cities": [...],
"notes": [...]
}
}判讀重點:
status為unknown時代表無法判斷,不可當成照常上班上課。conditional表示只有部分地區、學制或時段停止,要看cities[].rows。reason不是null時結果仍可能改變(live為即時頁,當天仍可能更新)。昨天到 21 天前常是
unknown/pending:即時頁只有今天與明天,歸檔通常延遲數天才收錄。請以各縣市政府公告為準。
MCP 資源
伺服器提供以下資源:
taiwan-holidays://years- 支援的年份列表taiwan-holidays://holidays/{year}- 指定年份的完整假期資料taiwan-holidays://stats/{year}- 指定年份的統計資訊
🔍 故障排除
常見問題
1. 無法連接到伺服器
問題:Claude Desktop 顯示 "無法連接到 MCP 伺服器"
解決方案:
# 檢查 Node.js 版本(需要 22+)
node --version
# 重新安裝套件
npm uninstall -g taiwan-holiday-mcp
npm install -g taiwan-holiday-mcp
# 測試伺服器
taiwan-holiday-mcp --version2. 日期格式錯誤
問題:收到 "無效的日期格式" 錯誤
解決方案:
確保使用正確格式:
YYYY-MM-DD或YYYYMMDD檢查日期是否有效(例如:2025-02-30 是無效日期)
3. 網路連接問題
問題:無法獲取假期資料
解決方案:
# 檢查網路連接
curl -I https://cdn.jsdelivr.net/gh/ruyut/TaiwanCalendar/data/2025.json
# 清除快取(如果有問題)
rm -rf ~/.taiwan-holiday-mcp-cache除錯模式
啟用詳細日誌:
taiwan-holiday-mcp --debug效能調整
如果查詢速度較慢:
檢查網路連接
確認快取機制正常運作
考慮使用本地資料來源
🧪 開發與測試
詳細的開發說明請參考 DEVELOPMENT.md。
本地開發
# 複製專案
git clone https://github.com/lis186/taiwan-holiday-mcp.git
cd taiwan-holiday-mcp
# 安裝依賴
npm install
# 執行測試
npm test
# 建置專案
npm run build
# 啟動開發模式
npm run dev測試覆蓋率
npm run test:coverage目前測試覆蓋率:93.68% statements(522 個測試通過,另有 8 個因環境略過)
核心模組覆蓋率(statements):
SmartCache: 98.97% ✅
HealthMonitor: 98.78% ✅
DateParser: 98.97% ✅
CircuitBreaker: 100% ✅
GracefulShutdown: 89.42% ✅
變異測試為選用,不在 CI。執行 npm run test:mutation(Stryker),目前分數 98.51%。
📊 效能指標
首次 API 呼叫:< 2 秒
快取 API 呼叫:< 100ms
併發處理:支援 10+ 併發請求
記憶體使用:< 50MB
測試穩定性:522 個測試通過(另有 8 個因環境略過)
程式碼覆蓋率:93.68% statements(遠超業界 80% 標準)
🤝 貢獻指南
歡迎貢獻!請遵循以下步驟:
Fork 專案
建立功能分支 (
git checkout -b feature/amazing-feature)提交變更 (
git commit -m 'Add amazing feature')推送到分支 (
git push origin feature/amazing-feature)開啟 Pull Request
⚠️ 免責聲明
資料來源與準確性
本專案的台灣假期資料來源於 TaiwanCalendar 開源專案,該專案基於中華民國政府公告的官方假期資訊。
颱風假(天然災害停止上班上課)資料來源:今天、明天讀行政院人事行政總處的 天然災害停止上班及上課情形 即時頁,其他日期讀 TaiwanTyphoonDays 歸檔。即時頁格式並非官方承諾, 可能隨時改變而導致無法解析;歸檔通常在事件後數天才收錄。停班停課請以各縣市政府的正式公告為準, 本專案回報「無法判斷」時,不代表照常上班上課。
重要聲明:
資料準確性:雖然我們努力確保資料的準確性,但本專案不保證所提供的假期資訊完全正確或即時更新。
官方資料:如需最準確的假期資訊,請以中華民國政府相關部門的官方公告為準。
資料更新:假期資料可能因政府政策調整而變更,本專案會盡力跟進更新,但可能存在延遲。
使用責任:使用者應自行驗證重要日期的假期狀態,特別是用於商業或法律用途時。
服務可用性
本服務依賴外部資料來源,可能因網路問題或資料來源異常而暫時無法使用
我們不保證服務的 100% 可用性或回應時間
建議在關鍵應用中實作適當的錯誤處理和備援機制
責任限制
在法律允許的最大範圍內,本專案的作者和貢獻者不對因使用本軟體而產生的任何直接、間接、偶然、特殊或後果性損害承擔責任。
🔗 相關專案
taiwan-holiday-cli—— 同一資料來源的命令列工具,適合終端機與腳本使用taiwan-holiday-skills—— 打包好的 Claude Agent Skill(底層透過 CLI 呼叫)
三個專案共享 MAJOR 版號,目前為 3.x 世代。
📄 授權條款
本專案採用 MIT 授權條款。詳見 LICENSE 檔案。
🙏 致謝
TaiwanCalendar - 提供準確的台灣假期資料
Model Context Protocol - 提供標準化的 AI 工具協議
📞 支援
支援年份: 2017 年起,上限跟隨上游資料(新年度發布即自動支援)
MCP SDK: @modelcontextprotocol/sdk ^1.13.0
Node.js 需求: ≥ 22.0.0
品質狀態: 企業級生產就緒 ✅
Available Tools
6 toolscheck_holidayB
檢查指定日期是否為台灣假期
Inputs: date (required).
check_typhoon_closureA
查詢台灣颱風假(天然災害停止上班上課)。今天、明天讀行政院人事行政總處(DGPA)即時頁,其他日期讀 2001-07-30 起的歸檔。 頂層 work/school 的 status 判讀規則:
stopped:全縣市停止,時段見 period/from。
conditional:只有部分地區、學制或時段停止,必須逐一讀 cities[].rows 判斷是否適用使用者所在地;未指定縣市時只要有任何停止就是 conditional。
normal:有公告且照常,或確定當日無公告。
unknown:無法判斷。絕對不可當成「照常上班上課」回答,應告知無法確認並請使用者查看縣市政府或 DGPA 公告。 reason 非 null 代表結果仍可能改變:live 為即時頁、當天仍可能更新;pending 為歸檔可能尚未收錄(昨天到 21 天前常見);source_not_ready 為當年度資料尚未產生。 回答時請轉述 summary 與 notes,並以各縣市政府公告為準。
Inputs: city, date.
get_holidays_in_rangeA
獲取指定日期範圍內的所有台灣假期
Inputs: end_date (required), start_date (required).
get_holiday_statsC
獲取指定年份或年月的台灣假期統計資訊
Inputs: year (required), month.
get_next_holidaysA
取得指定日期之後的接下來 N 個台灣假期。未指定日期時以台北時區的今天為起算日(不含當天)。可略過一般週末,只保留具名假日。補班日不是假期,不會出現在結果裡。結果含 searchedThrough 與 truncatedByData;搜尋被上游最後一個已發布年度截斷時 truncatedByData 為 true。起算日晚於已發布資料時不會回「查無假期」。
Inputs: date, count, skip_weekends.
get_workdaysA
計算工作天數。指定 year 與 month 可查整月;指定 start_date 與 end_date 可查區間(含起迄日)。週末與假期不計入工作天,補班日(補行上班)計入工作天並另外列出。上游筆數與日曆天數不符時回報錯誤,不會把缺日當成工作天。兩種查法請擇一,不要同時指定。
Inputs: year, month, end_date, start_date.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
The tools are mostly distinct: single-date holiday checking, range listing, next-holiday lookup, statistics, workday calculation, and typhoon closures each serve a clear purpose. There is minor overlap between check_holiday and using get_holidays_in_range or get_workdays for a single date, but the descriptions make the intended boundaries reasonably clear.
All tool names use consistent snake_case with a verb_noun structure. The check_ prefix is used for boolean/status-style checks and get_ for retrieval or calculation, which is predictable and readable.
Six tools is well-scoped for a Taiwan holiday server. Each tool covers a distinct common query type, and there is no obvious bloat or missing essential operation at the count level.
The surface covers the main holiday workflows: single-date checks, range queries, statistics, upcoming holidays, workday calculations, and typhoon closures. Minor gaps remain, such as workday calculations not explicitly accounting for typhoon closures and no standalone holiday-by-name lookup, but agents can mostly work around these.
Maintenance
Related MCP Connectors
Public holiday data for 30+ countries. Check holidays, working days and calendars via AI assistants.
Taiwan data for AI agents: THSR/TRA timetables, TWSE/TPEx stocks, invoice lottery, garbage, outages
MCP server for China public holidays and lunar calendar: solar-lunar conversion and yearly schedule.
A Model Context Protocol server for Wix AI tools
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that enables natural language interaction with Google Calendar, allowing users to view, create, update, and delete calendar events through context-aware operations.79 npm1MIT
- AlicenseAqualityDmaintenanceA Model Context Protocol server that allows large language models to search for and analyze Chinese railway (12306) tickets through a simple API interface.813,273 npm19MIT
- AlicenseBqualityDmaintenanceA Taiwan holiday query server based on Model Context Protocol (MCP), providing accurate information on scheduled holidays and make-up working days, supporting multiple query methods and integration with AI tools.32Apache 2.0
- FlicenseBqualityDmaintenanceA Model Context Protocol server that enables users to manage employee leave through natural language. It provides tools to check leave balances, apply for leave, and view leave history via Claude integration.3-