A
licenseNot graded
qualityD
maintenanceA 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.
164
1
MIT
Taiwan Holiday MCP Server
by lis186
The Taiwan Holiday MCP Server allows users to query and analyze Taiwan's public holidays using the Model Context Protocol (MCP).
Check Specific Holidays: Verify if a given date is a public holiday in Taiwan using
check_holiday, supporting formatsYYYY-MM-DDandYYYYMMDD.Range Query: Retrieve all public holidays within a specified date range using
get_holidays_in_range.Statistical Analysis: Obtain detailed statistics regarding public holidays for a given year or a specific month using
get_holiday_stats, including totals, types, and summaries.Access Raw Data: Retrieve raw holiday data and statistical information for specific years.
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 "Install 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 Serverwhat 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 提供的政府公告假期資訊
🚀 即時查詢：支援單日查詢、範圍查詢和統計查詢
📅 多種日期格式：支援
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： 會提供該月份的假期統計，包含國定假日和重要節慶資訊。
進階應用
🎯 智慧假期分析
你： "幫我分析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 個假期"
}
}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 --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目前測試覆蓋率：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% 標準）
🤝 貢獻指南
歡迎貢獻！請遵循以下步驟：
Fork 專案
建立功能分支 (
git checkout -b feature/amazing-feature)提交變更 (
git commit -m 'Add amazing feature')推送到分支 (
git push origin feature/amazing-feature)開啟 Pull Request
⚠️ 免責聲明
資料來源與準確性
本專案的台灣假期資料來源於 TaiwanCalendar 開源專案，該專案基於中華民國政府公告的官方假期資訊。
重要聲明：
資料準確性：雖然我們努力確保資料的準確性，但本專案不保證所提供的假期資訊完全正確或即時更新。
官方資料：如需最準確的假期資訊，請以中華民國政府相關部門的官方公告為準。
資料更新：假期資料可能因政府政策調整而變更，本專案會盡力跟進更新，但可能存在延遲。
使用責任：使用者應自行驗證重要日期的假期狀態，特別是用於商業或法律用途時。
服務可用性
本服務依賴外部資料來源，可能因網路問題或資料來源異常而暫時無法使用
我們不保證服務的 100% 可用性或回應時間
建議在關鍵應用中實作適當的錯誤處理和備援機制
責任限制
在法律允許的最大範圍內，本專案的作者和貢獻者不對因使用本軟體而產生的任何直接、間接、偶然、特殊或後果性損害承擔責任。
🔗 相關專案
taiwan-holiday-cli—— 同一資料來源的命令列工具，適合終端機與腳本使用taiwan-holiday-skills—— 打包好的 Claude Agent Skill（底層透過 CLI 呼叫）
三個專案共享 MAJOR 版號，目前為 2.x 世代。
📄 授權條款
本專案採用 MIT 授權條款。詳見 LICENSE 檔案。
🙏 致謝
TaiwanCalendar - 提供準確的台灣假期資料
Model Context Protocol - 提供標準化的 AI 工具協議
📞 支援
支援年份: 2017 年起，上限跟隨上游資料（新年度發布即自動支援）
MCP SDK: @modelcontextprotocol/sdk ^1.13.0
Node.js 需求: ≥ 18.0.0
品質狀態: 企業級生產就緒 ✅
Available Tools
3 toolscheck_holidayB
檢查指定日期是否為台灣假期
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | 要查詢的日期，支援格式：YYYY-MM-DD 或 YYYYMMDD |
TDQS
B3.1/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 behavioral disclosure. It states what the tool does but doesn't describe how it behaves: it doesn't mention data sources, accuracy, update frequency, error handling, or response format. For a tool with no annotations, this leaves significant gaps in understanding its operational characteristics.
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 directly states the tool's purpose without any unnecessary words. It's appropriately sized and front-loaded, with every word earning its place. No structural issues or verbosity detract from its clarity.
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?
Given the tool's low complexity (1 parameter, no nested objects) and high schema coverage, the description is minimally adequate. However, with no output schema and no annotations, it doesn't explain what the return value looks like (e.g., boolean, holiday name, or error messages). For a simple lookup tool, this is acceptable but leaves room for improvement.
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 has 100% description coverage, with the 'date' parameter fully documented in the schema itself (format, pattern). The description adds no additional parameter semantics beyond what's already in the schema. According to the rules, when schema_description_coverage is high (>80%), the baseline is 3 even with no param info in the description.
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's purpose: '檢查指定日期是否為台灣假期' (Check if a specified date is a Taiwan holiday). It uses a specific verb ('檢查' - check) and resource ('台灣假期' - Taiwan holidays). However, it doesn't explicitly distinguish itself from sibling tools like 'get_holidays_in_range' or 'get_holiday_stats', which reduces it from a perfect score.
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?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools or suggest scenarios where this single-date check would be preferred over range-based queries or statistical tools. The agent must infer usage from the tool name and description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_holidays_in_rangeB
獲取指定日期範圍內的所有台灣假期
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | Yes | 開始日期，支援格式：YYYY-MM-DD 或 YYYYMMDD | |
| end_date | Yes | 結束日期，支援格式：YYYY-MM-DD 或 YYYYMMDD |
TDQS
B3.1/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 burden. It states what the tool does but lacks behavioral details: no mention of permissions needed, rate limits, whether it returns structured data or raw text, error handling, or pagination. For a read operation with no annotation coverage, this leaves significant gaps in understanding how it behaves.
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?
Extremely concise with a single sentence that directly states the purpose. No wasted words or redundant information. It's front-loaded and efficiently communicates the core functionality without unnecessary elaboration.
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?
Given the tool's moderate complexity (date-range query), no annotations, and no output schema, the description is minimally adequate. It covers the basic purpose but lacks details on output format, error cases, or behavioral traits. It meets the bare minimum for a read operation but doesn't provide enough context for robust agent use without additional assumptions.
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?
Schema description coverage is 100%, with both parameters ('start_date', 'end_date') fully documented in the schema regarding format and patterns. The description adds no additional parameter semantics beyond implying a date range, which is already clear from the schema. Baseline 3 is appropriate as the schema does the heavy lifting.
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 action ('獲取' - get/fetch) and resource ('台灣假期' - Taiwan holidays) with scope ('指定日期範圍內' - within a specified date range). It distinguishes from sibling 'check_holiday' (likely checks a single date) and 'get_holiday_stats' (likely provides statistics), though not explicitly. The purpose is specific but lacks explicit sibling differentiation.
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 on when to use this tool versus alternatives like 'check_holiday' or 'get_holiday_stats'. The description implies usage for fetching multiple holidays in a range, but doesn't state exclusions or prerequisites. It's minimal, relying on inference from the name and description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_holiday_statsC
獲取指定年份或年月的台灣假期統計資訊
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| year | Yes | 要查詢的年份 | |
| month | No | 要查詢的月份（可選），1-12 |
TDQS
C2.9/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states what the tool does (retrieve holiday statistics) but lacks details on behavioral traits such as whether it's read-only, any rate limits, authentication needs, or what the output format might be (e.g., counts, lists, or aggregated data). This leaves significant gaps for an agent to understand how to handle the tool effectively.
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, efficient sentence that directly states the tool's purpose without unnecessary words. It's front-loaded with the core action and resource, making it easy to parse quickly. Every part of the sentence contributes to understanding the tool's function.
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 the complexity of a tool that retrieves statistical information, the description is incomplete. With no annotations and no output schema, it fails to explain what '統計資訊' (statistics information) entails—such as the type of data returned (e.g., counts, percentages, or detailed breakdowns). This lack of context makes it harder for an agent to use the tool correctly without additional information.
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 description coverage is 100%, with clear descriptions for both parameters ('year' and 'month') including constraints. The description adds minimal value beyond the schema by mentioning '指定年份或年月' (specified year or year-month), which aligns with the schema but doesn't provide additional semantic context or usage examples. Baseline 3 is appropriate as the schema handles most of the parameter documentation.
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 action ('獲取' meaning 'get' or 'retrieve') and the resource ('台灣假期統計資訊' meaning 'Taiwan holiday statistics information'), specifying it's for a given year or year-month. However, it doesn't explicitly differentiate from sibling tools like 'check_holiday' or 'get_holidays_in_range', which might have overlapping purposes but different scopes or outputs.
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?
The description provides no guidance on when to use this tool versus the sibling tools 'check_holiday' or 'get_holidays_in_range'. It mentions the parameters (year or year-month) but doesn't clarify the context or alternatives, leaving the agent to infer usage based on tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
TDQS
A3.6/5.0
Disambiguation5/5
Each tool has a clearly distinct purpose: check_holiday verifies a single date, get_holidays_in_range lists holidays over a period, and get_holiday_stats provides statistical summaries. There is no overlap in functionality, making tool selection straightforward for an agent.
Naming Consistency5/5
All tools follow a consistent verb_noun naming pattern (check_holiday, get_holidays_in_range, get_holiday_stats) with clear, descriptive verbs. The naming is uniform and predictable across the set.
Tool Count5/5
With 3 tools, the server is well-scoped for its purpose of providing Taiwan holiday information. Each tool serves a unique and essential function, and the count is appropriate without being too sparse or bloated.
Completeness5/5
The tool set comprehensively covers the domain of Taiwan holiday queries: it supports checking individual dates, retrieving lists over ranges, and obtaining statistical data. There are no obvious gaps in functionality for this focused purpose.
Maintenance
ActivityMaintained
ResponsivenessSyncing
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Public holiday data for 30+ countries. Check holidays, working days and calendars via AI assistants.
A Model Context Protocol server for Wix AI tools
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Real public holiday lookup for 206 countries via a rule-based calendar engine. Paid via x402.
Related MCP Servers
- AlicenseAqualityDmaintenanceA Model Context Protocol server that allows large language models to search for and analyze Chinese railway (12306) tickets through a simple API interface.88,31318MIT
- 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
Appeared in Searches
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/lis186/taiwan-holiday-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server