Taiwan Holiday MCP Server

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

✨ 特色功能

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

🚀 快速開始

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.json
Windows: %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： 會提供該月份的假期統計，包含國定假日和重要節慶資訊。

進階應用

🎯 智慧假期分析

你： "幫我分析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-2025)
month (number, 可選): 月份 (1-12)

回傳：

{
  "success": true,
  "data": {
    "year": 2025,
    "statistics": {
      "year": 2025,
      "totalHolidays": 115,
      "nationalHolidays": 113,
      "compensatoryDays": 2,
      "holidayTypes": {...}
    },
    "summary": "2025 年共有 115 個假期"
  }
}

MCP 資源

伺服器提供以下資源：

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

🔍 故障排除

常見問題

1. 無法連接到伺服器

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

解決方案：

# 檢查 Node.js 版本（需要 18+）
node --version

# 重新安裝套件
npm uninstall -g taiwan-holiday-mcp
npm install -g taiwan-holiday-mcp

# 測試伺服器
taiwan-holiday-mcp --version

2. 日期格式錯誤

問題：收到 "無效的日期格式" 錯誤

解決方案：

確保使用正確格式：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

目前測試覆蓋率：77.84%（120 個測試案例，100% 通過）

📊 效能指標

首次 API 呼叫：< 2 秒
快取 API 呼叫：< 100ms
併發處理：支援 10+ 併發請求
記憶體使用：< 100MB

🤝 貢獻指南

歡迎貢獻！請遵循以下步驟：

Fork 專案
建立功能分支 (git checkout -b feature/amazing-feature)
提交變更 (git commit -m 'Add amazing feature')
推送到分支 (git push origin feature/amazing-feature)
開啟 Pull Request

⚠️ 免責聲明

資料來源與準確性

本專案的台灣假期資料來源於 TaiwanCalendar 開源專案，該專案基於中華民國政府公告的官方假期資訊。

重要聲明：

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

服務可用性

本服務依賴外部資料來源，可能因網路問題或資料來源異常而暫時無法使用
我們不保證服務的 100% 可用性或回應時間
建議在關鍵應用中實作適當的錯誤處理和備援機制

責任限制

在法律允許的最大範圍內，本專案的作者和貢獻者不對因使用本軟體而產生的任何直接、間接、偶然、特殊或後果性損害承擔責任。

📄 授權條款

本專案採用 MIT 授權條款。詳見 LICENSE 檔案。

🙏 致謝

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

📞 支援

GitHub Issues: 回報問題
文件: 完整文件

版本: 1.0.0
最後更新: 2025-06-11
Node.js 需求: ≥ 18.0.0

You must be authenticated.

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

Tools

A Model Context Protocol server that provides accurate Taiwan holiday and makeup workday information, enabling users to query single dates, date ranges, and holiday statistics through natural language.

Related Resources

Reddit Discussion about this server

Related MCP Servers

Google Calendar MCP Server
amornpan
-
security
F
license
-
quality
Model Context Protocol server that provides seamless access to Google Calendar API with asynchronous operation support, enabling efficient calendar management through a standardized interface.
Last updated -
Python
Google Workspace MCP Server
rishipradeep-think41
A
security
A
license
A
quality
A Model Context Protocol server that provides tools for interacting with Gmail and Calendar APIs, enabling programmatic management of emails and calendar events.
Last updated -
8
13
JavaScript
MIT License
MCP Apple Calendars
shadowfax92
-
security
F
license
-
quality
A Model Context Protocol server for AI models to access and manipulate Apple Calendar data on macOS through a standardized interface.
Last updated -
5
TypeScript
Attendance Management MCP Server
shineliang
-
security
-
license
-
quality
A Model Context Protocol server that enables querying attendance information and managing employee leave requests, overtime requests, and schedules.
Last updated -
Python

View all related MCP servers