Skip to main content
Glama
BACH-AI-Tools

taiwan-holiday-mcp

by BACH-AI-Tools
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Taiwan Holiday MCP Server

Node.js Version npm version License: MIT Install MCP Server

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

基于原项目: 此项目基于 taiwan-holiday-mcp 修改而来

✨ 特色功能

  • 🇹🇼 準確的台灣假期資料：基於 TaiwanCalendar 提供的政府公告假期資訊

  • 🚀 即時查詢：支援單日查詢、範圍查詢和統計查詢

  • 📅 多種日期格式：支援 YYYY-MM-DD 和 YYYYMMDD 格式

  • 🔄 智慧快取：自動快取資料，提升查詢效能

  • 🛠️ MCP 標準：完全相容 Model Context Protocol 規範

  • 🎯 AI 友善：專為 Claude Desktop、Cursor 等 AI 工具設計

  • 📊 豐富統計：提供假期統計和分析功能

  • 🌐 跨平台：支援 Windows、macOS 和 Linux

Related MCP server: Taiwan Holiday MCP Server

🚀 快速開始

NPX 直接使用（推薦）

最簡單的使用方式，無需安裝：

npx @bachstudio/taiwan-holiday-mcp

本地安裝

npm install -g @bachstudio/taiwan-holiday-mcp
taiwan-holiday-mcp

開發環境安裝

git clone https://github.com/BACH-AI-Tools/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": ["@bachstudio/taiwan-holiday-mcp"]
    }
  }
}

設定檔位置：

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Cursor 設定

點擊以下按鈕直接安裝。

Install MCP Server

Windsurf 設定

在專案的 .cursorrules 或設定檔中新增：

{
  "mcp": {
    "servers": {
      "taiwan-holiday": {
        "command": "npx",
        "args": ["@bachstudio/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-2026)

  • 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 @bachstudio/taiwan-holiday-mcp
npm install -g @bachstudio/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

效能調整

如果查詢速度較慢：

  1. 檢查網路連接

  2. 確認快取機制正常運作

  3. 考慮使用本地資料來源

🧪 開發與測試

詳細的開發說明請參考 DEVELOPMENT.md。

本地開發

# 複製專案
git clone https://github.com/BACH-AI-Tools/taiwan-holiday-mcp.git
cd taiwan-holiday-mcp

# 安裝依賴
npm install

# 執行測試
npm test

# 建置專案
npm run build

# 啟動開發模式
npm run dev

測試覆蓋率

npm run test:coverage

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

核心模組覆蓋率：

  • SmartCache: 98.97% ✅

  • HealthMonitor: 98.78% ✅

  • DateParser: 97.77% ✅

  • CircuitBreaker: 100% ✅

  • GracefulShutdown: 88.34% ✅

📊 效能指標

  • 首次 API 呼叫：< 2 秒

  • 快取 API 呼叫：< 100ms

  • 併發處理：支援 10+ 併發請求

  • 記憶體使用：< 50MB

  • 測試穩定性：100% 通過率，企業級品質標準

  • 程式碼覆蓋率：92.34%（遠超業界 80% 標準）

🤝 貢獻指南

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

  1. Fork 專案

  2. 建立功能分支 (git checkout -b feature/amazing-feature)

  3. 提交變更 (git commit -m 'Add amazing feature')

  4. 推送到分支 (git push origin feature/amazing-feature)

  5. 開啟 Pull Request

⚠️ 免責聲明

資料來源與準確性

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

重要聲明：

  1. 資料準確性：雖然我們努力確保資料的準確性，但本專案不保證所提供的假期資訊完全正確或即時更新。

  2. 官方資料：如需最準確的假期資訊，請以中華民國政府相關部門的官方公告為準。

  3. 資料更新：假期資料可能因政府政策調整而變更，本專案會盡力跟進更新，但可能存在延遲。

  4. 使用責任：使用者應自行驗證重要日期的假期狀態，特別是用於商業或法律用途時。

服務可用性

  • 本服務依賴外部資料來源，可能因網路問題或資料來源異常而暫時無法使用

  • 我們不保證服務的 100% 可用性或回應時間

  • 建議在關鍵應用中實作適當的錯誤處理和備援機制

責任限制

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

📄 授權條款

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

🙏 致謝

📞 支援

版本: 1.0.4 最後更新: 2025-10-10
支援年份: 2017-2026
MCP SDK: @modelcontextprotocol/sdk ^1.13.0
Node.js 需求: ≥ 18.0.0
品質狀態: 企業級生產就緒 ✅

Available Tools

3 tools
check_holidayB

檢查指定日期是否為台灣假期

ParametersJSON Schema
NameRequiredDescriptionDefault
dateYes要查詢的日期，支援格式：YYYY-MM-DD 或 YYYYMMDD

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description does not disclose behavioral details such as return format, handling of invalid dates, or what constitutes a 'holiday' (e.g., official calendar). The description carries the full burden and is minimal.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence in Chinese that is front-loaded and free of fluff. Every word contributes to the tool's purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given there is no output schema or annotations, the description should explain what the tool returns (e.g., true/false) and any relevant context about holiday definitions. It does neither, making it incomplete for an agent to fully understand the tool's behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema covers the single parameter (date) with format constraints and description. The tool description adds no additional parameter semantics beyond the schema, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool checks if a specified date is a Taiwan holiday. It uses a specific verb ('check') and resource ('date is Taiwan holiday'), distinguishing it from sibling tools that handle ranges or statistics.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus the alternatives (get_holidays_in_range, get_holiday_stats). The intended use case (single-date checking) is implied by the name and description but not explicitly contrasted with siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_holidays_in_rangeA

獲取指定日期範圍內的所有台灣假期

ParametersJSON Schema
NameRequiredDescriptionDefault
end_dateYes結束日期，支援格式：YYYY-MM-DD 或 YYYYMMDD
start_dateYes開始日期，支援格式：YYYY-MM-DD 或 YYYYMMDD

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of disclosing behavior. However, it only states the purpose (retrieving holidays in a range) and does not mention return format, error handling, rate limits, or whether it is a read-only operation. This leaves significant behavioral context unspecified.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that front-loads the core action and resource. It contains no wasted words and is appropriately minimal for the tool's simplicity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with only two parameters, and the schema adequately documents those. However, there is no output schema, and the description does not clarify the return structure or format (e.g., a list of holiday objects). The description implies the result is all holidays in the range, but a bit more detail would make it more complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema covers 100% of parameters with descriptions of date formats (YYYY-MM-DD or YYYYMMDD). The description adds no additional parameter semantics beyond what the schema already provides, so the baseline score of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb '獲取' (get) with a clear resource '所有台灣假期' (all Taiwan holidays) and scope '指定日期範圍內' (within specified date range). This clearly differentiates it from sibling tools like check_holiday (which checks a single date) and get_holiday_stats (which provides statistics).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is used for retrieving holidays within a date range, but it does not explicitly state when to use this tool versus alternatives like check_holiday or get_holiday_stats. No exclusions or alternative guidance is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_holiday_statsB

獲取指定年份或年月的台灣假期統計資訊

ParametersJSON Schema
NameRequiredDescriptionDefault
yearYes要查詢的年份
monthNo要查詢的月份（可選），1-12

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full responsibility. It only states the function without disclosing behavioral traits like return format, aggregation details, or potential limitations (e.g., date boundaries). This is a significant gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence that front-loads the verb and resource, with no unnecessary words. It is appropriately concise for a simple tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and no annotations, the description omits what 'statistics' means or what the response contains. For a tool with two parameters, this is under-specified and leaves the agent guessing about the return value.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema covers 100% of parameters, with year and month each having descriptions. The description adds minimal semantic value, only reaffirming that the tool works for a year or year-month combination, which is already implied by the parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves Taiwan holiday statistics for a specified year or year-month, using a specific verb (獲取) and resource (台灣假期統計資訊). However, it does not explicitly differentiate from sibling tools like check_holiday or get_holidays_in_range, though the 'statistics' focus implies a different use case.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implicitly conveys usage: use when you need Taiwan holiday statistics for a year or month. It lacks explicit guidance on when to prefer this tool over siblings, such as when checking a single date or a range.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv1.0.5
    • First observedcheck_holiday
    • First observedget_holiday_stats
    • First observedget_holidays_in_range
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.8/5.0

Scored across 3 tools

Disambiguation5/5

Each tool targets a distinct query type: a single date check, a date range listing, and aggregated statistics. There is no overlap in purpose, making selection unambiguous.

Naming Consistency5/5

All tool names follow a clear verb_noun pattern: check_holiday, get_holidays_in_range, get_holiday_stats. The minor singular/plural variation is semantically appropriate and does not break consistency.

Tool Count5/5

With only 3 tools, the server is tightly scoped to its niche purpose (Taiwan holiday lookup). Each tool covers a distinct and necessary function without bloat.

Completeness5/5

The tool set fully covers the core holiday querying lifecycle: single-date lookup, range listing, and statistical summaries. Since holidays are fixed data, no update/delete operations are needed, so there are no gaps.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Taiwan Holiday MCP Server

    lis186
    A
    license
    A
    quality
    D
    maintenance
    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.
    3
    8 npm
    27
    MIT

  • taiwan-holiday

    xiaobenyang-com
    A
    license
    B
    quality
    D
    maintenance
    A 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.
    3
    2
    Apache 2.0

  • Nager MCP v101

    Traia-IO
    F
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that provides access to the Nager.Date API for retrieving public holiday information across various countries. It enables AI agents to interact with holiday data and date-related endpoints through standardized Model Context Protocol tools.
    -