Taiwan Holiday

Provides Taiwan national holidays and compensatory workday information. Data is fetched and cached automatically.

一個基於 Model Context Protocol (MCP) 的台灣假期查詢伺服器，提供準確的台灣國定假日和補班日資訊。

- 🇹🇼準確的台灣假期資料：基於TaiwanCalendar提供的政府公告假期資訊
- 🚀即時查詢：支援單日查詢、範圍查詢和統計查詢
- 📅多種日期格式：支援YYYY-MM-DD和YYYYMMDD格式
- 🔄智慧快取：自動快取資料，提升查詢效能
- 🛠️MCP 標準：完全相容 Model Context Protocol 規範
- 🎯AI 友善：專為 Claude Desktop、Cursor 等 AI 工具設計
- 📊豐富統計：提供假期統計和分析功能
- 🌐跨平台：支援 Windows、macOS 和 Linux

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

{ "mcpServers": { "taiwan-holiday": { "command": "npx", "args": ["taiwan-holiday-mcp"] } } }

- macOS:~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:%APPDATA%\Claude\claude_desktop_config.json

{ "mcp": { "servers": { "taiwan-holiday": { "command": "npx", "args": ["taiwan-holiday-mcp"] } } } }

安裝完成後，你可以直接在 Claude Desktop 中用自然語言與 AI 對話，詢問台灣假期相關問題：

- ✅ 2025年10月10日是國慶日，是假期
- 📅 2025年1月共有14個假期，包含春節連假
- 📊 2025年總共有115個假期

你："我想規劃2025年第一季的旅遊，幫我找出有哪些連假可以安排？"

- 春節連假：1月27日-31日（5天）
- 228連假：2月28日-3月2日（3天）
- 其他週末假期安排建議

- date(string): 日期，格式為YYYY-MM-DD或YYYYMMDD

{ "success": true, "data": { "date": "2025-10-10", "isHoliday": true, "description": "國慶日", "week": "五", "normalizedDate": "20251010" } }

- 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 個假期" } }

- 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 個假期" } }

- taiwan-holidays://years- 支援的年份列表
- taiwan-holidays://holidays/{year}- 指定年份的完整假期資料
- taiwan-holidays://stats/{year}- 指定年份的統計資訊

問題：Claude Desktop 顯示 "無法連接到 MCP 伺服器"

# 檢查 Node.js 版本（需要 18+） node --version # 重新安裝套件 npm uninstall -g taiwan-holiday-mcp npm install -g taiwan-holiday-mcp # 測試伺服器 taiwan-holiday-mcp --version

- 確保使用正確格式：YYYY-MM-DD或YYYYMMDD
- 檢查日期是否有效（例如：2025-02-30 是無效日期）

# 檢查網路連接 curl -I https://cdn.jsdelivr.net/gh/ruyut/TaiwanCalendar/data/2025.json # 清除快取（如果有問題） rm -rf ~/.taiwan-holiday-mcp-cache

# 複製專案 git clone https://github.com/lis186/taiwan-holiday-mcp.git cd taiwan-holiday-mcp # 安裝依賴 npm install # 執行測試 npm test # 建置專案 npm run build # 啟動開發模式 npm run dev

- SmartCache: 98.97% ✅
- HealthMonitor: 98.78% ✅
- DateParser: 97.77% ✅
- CircuitBreaker: 100% ✅
- GracefulShutdown: 88.34% ✅

- 首次 API 呼叫：< 2 秒
- 快取 API 呼叫：< 100ms
- 併發處理：支援 10+ 併發請求
- 記憶體使用：< 50MB
- 測試穩定性：100% 通過率，企業級品質標準
- 程式碼覆蓋率：92.34%（遠超業界 80% 標準）
- Fork 專案
- 建立功能分支 (git checkout -b feature/amazing-feature)
- 提交變更 (git commit -m 'Add amazing feature')
- 推送到分支 (git push origin feature/amazing-feature)
- 開啟 Pull Request

本專案的台灣假期資料來源於TaiwanCalendar開源專案，該專案基於中華民國政府公告的官方假期資訊。
- 資料準確性：雖然我們努力確保資料的準確性，但本專案不保證所提供的假期資訊完全正確或即時更新。
- 官方資料：如需最準確的假期資訊，請以中華民國政府相關部門的官方公告為準。
- 資料更新：假期資料可能因政府政策調整而變更，本專案會盡力跟進更新，但可能存在延遲。
- 使用責任：使用者應自行驗證重要日期的假期狀態，特別是用於商業或法律用途時。

- taiwan-holiday-cli—— 同一資料來源的命令列工具，適合終端機與腳本使用
- taiwan-holiday-skills—— 打包好的 Claude Agent Skill（底層透過 CLI 呼叫）

- TaiwanCalendar- 提供準確的台灣假期資料
- Model Context Protocol- 提供標準化的 AI 工具協議

An MCP server for ActivityWatch, allowing interaction with your personal time tracking data.