Calendarific MCP Server

日历MCP服务器

一个用于假日数据的模型上下文协议（MCP）服务器，由FastMCP和MCP框架构建。该服务器提供与假日相关的工具，人工智能助手可以使用日历API检索不同国家和年份的公共假日。

特性

🎯 核心功能

• 全球假期数据：访问230多个国家和地区的公共假期
• 多年支持：检索任何一年的假期（过去、现在或未来）
• 详细信息：获取假日名称、日期和其他元数据

🔌 集成与兼容性

• MCP协议：AI助手的本地模型上下文协议支持
• FastMCP框架：基于现代高性能MCP实施
• 交叉平台的：适用于Windows、macOS和Linux

🌍 数据覆盖

• ISO标准：使用ISO 3166-1 alpha-2国家代码（美国、英国、伊利诺伊州等）
• 实时API：始终通过日历API提供最新的假日信息
• 错误处理：针对API问题和无效输入的强大错误管理

需求

• Python 3.13+
• 紫外线 包管理器
• 日历 API密钥

安装

手动安装

1. 克隆此存储库：

   git clone https://github.com/yourusername/calendarific-mcp-server.git
   cd calendarific-mcp-server

1. 使用uv安装依赖项：

   uv venv
   uv pip install -e .

1. 创建一个 .env 项目根目录中的带有Calendarfic API密钥的文件：

   CALENDARIFIC_API_KEY=your_api_key_here

用法

运行服务器：

python main.py

服务器将启动并通过stdio传输连接MCP通信。

可用工具

get_public_holidays

获取特定国家和年份的公共假期列表。

参数：

• country （str）：ISO 3166-1 alpha-2国家代码（例如，“US”、“GB”、“IL”）
• year （int）：获得假期的年份

退货：

• 假期列表格式：“YYYY-MM-DD：假期名称”

例子：

# Get US holidays for 2024
holidays = await get_public_holidays("US", 2024)
# Returns: ["2024-01-01: New Year's Day", "2024-07-04: Independence Day", ...]

API密钥设置

1. 注册一个免费帐户 日历
2. 从仪表板获取API密钥
3. 将其添加到您的 .env 文件为 CALENDARIFIC_API_KEY

支持的国家

服务器支持日历API中提供的所有国家/地区。使用ISO 3166-1 alpha-2国家代码：

• US（美国）
• GB（英国）
• IL（以色列）
• CA（加拿大）
• AU（澳大利亚）
• 还有更多。..

错误处理

服务器包括全面的错误处理：

• 无效的API密钥错误
• 网络连接问题
• 国家代码无效
• API速率限制

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

支持

对于问题和疑问：

• 检查 日历API文档
• 在GitHub上打开一个问题
• 查阅MCP文档