AI导哈

日历MCP服务器

一个用于iCalendar feed管理和事件查询的模型上下文协议（MCP）服务器，支持多日历feed的事件跟踪、冲突检测和日程管理。

  • by amattas
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 amattas/calendar-mcp

使用说明

日历MCP服务器

用于iCalendar提要管理和事件查询的模型上下文协议（MCP）服务器。此服务器使Claude Desktop和其他MCP客户端能够与多个日历提要进行交互，以进行事件跟踪、冲突检测和日程管理。

特性

  • 多日历支持：监视多个iCalendar源（.ics URL）
  • 智能事件查询：按日期、范围或关键字搜索事件
  • 冲突检测：具有严重性级别的高级冲突分析
  • 动态饲料管理：动态添加/删除日历提要
  • 自动刷新：订阅源更新的可配置刷新间隔
  • 时区支持：适当的时区规范化和处理
  • Redis缓存：可选缓存以提高性能
  • HTTP API：通过HTTP进行远程访问，采用双因素身份验证

快速开始

Docker部署

对于生产HTTP访问：

# 1. Configure environment
cp .env.example .env.local
# Edit .env.local: set ICAL_FEED_CONFIGS and MCP_API_KEY

# 2. Run with Docker Compose
docker-compose up --build

# 3. Calculate your endpoint URLs
python scripts/verify_auth.py --api-key YOUR_KEY --domain localhost:8080 --no-https

# 4. Access endpoints
# Health (public): http://localhost:8080/app/health
# MCP: http://localhost:8080/app/{API_KEY}/{API_KEY_HASH}/mcp

配置

环境变量

必修的：

  • ICAL_FEED_CONFIGS -日历提要的JSON数组

可选：

  • TIMEZONE -IANA时区名称（默认值： UTC)
  • REFRESH_INTERVAL -刷新间隔分钟数（默认值： 60)
  • DEBUG -启用调试日志记录（默认值： false)

HTTP模式：

  • MCP_API_KEY -用于身份验证的API密钥（强烈推荐）
  • MD5_SALT -MD5哈希的盐（可选，建议增强安全性）
  • HOST -绑定地址（默认值： 0.0.0.0)
  • PORT -侦听端口（默认： 80)

Redis缓存（可选）：

  • REDIS_HOST -Redis主机名
  • REDIS_SSL_PORT -Redis SSL端口（默认： 6380)
  • REDIS_KEY -Redis访问密钥

日历源格式

[
  {
    "name": "Work",
    "url": "https://calendar.google.com/calendar/ical/YOUR_ID/basic.ics"
  },
  {
    "name": "Personal",
    "url": "https://outlook.office365.com/owa/calendar/YOUR_ID/calendar.ics"
  }
]

获取日历源URL

谷歌日历：

  1. 打开谷歌日历设置
  2. 选择日历→ “集成日历”
  3. 复制“iCal格式的秘密地址”

Outlook日历：

  1. 日历设置→ “共享日历”
  2. 发布日历
  3. 复制ICS链接

苹果日历：

  1. 右键单击日历→ “共享日历”
  2. 公开并复制URL（更改 webcal:// 到 https://)

部署

带有HTTP API的Docker

docker-compose up --build

入口点： server_remote.py 端口： 8080 身份验证： 双因子路径（API密钥+MD5哈希）

认证

服务器使用 双因素路径认证 需要API密钥及其MD5散列：

https://your-domain.com/app/{API_KEY}/{API_KEY_HASH}/mcp

哈希值计算如下 MD5(MD5_SALT + API_KEY) 当盐被配置时，或 MD5(API_KEY) 在传统模式下。

生成端点URL

Python脚本（推荐）：

python scripts/verify_auth.py --api-key YOUR_KEY --domain your-domain.com

Bash脚本：

scripts/get_mcp_url.sh YOUR_KEY your-domain.com

手动计算：

import hashlib
api_key = "your-api-key"
md5_salt = "your-salt"  # Optional
hash_input = f"{md5_salt}{api_key}" if md5_salt else api_key
api_key_hash = hashlib.sha256(hash_input.encode()).hexdigest()
print(f"https://domain.com/app/{api_key}/{api_key_hash}/mcp")

安全特性

防暴力保护：

  • 无效的身份验证路径在返回404之前会触发30秒的延迟
  • 这使得暴力攻击变得不切实际（例如，测试1000个密钥需要8个多小时）
  • 健康检查端点(/app/health)免于延误
  • 用源IP记录失败的尝试以进行监视

最佳实践：

  • 使用强API密钥（32+字节，使用 openssl rand -base64 32)
  • 配置 MD5_SALT 用于附加安全层
  • 监视重复失败的身份验证尝试的日志
  • 考虑在反向代理上进行基于IP的速率限制
  • 在生产环境中始终使用HTTPS以防止凭据被拦截

可用端点

  • 健康 (/health)：健康检查（公开，无需身份验证）
  • 主控程序 (/app/{KEY}/{HASH}/mcp)：MCP协议端点（经过身份验证）

证券收益

  1. 双因素保护：需要API密钥和哈希
  2. 哈希值未存储：运行时计算的哈希
  3. 路径混淆：即使有一个因素，端点也无法访问
  4. 无令牌交换：无状态身份验证

可用的MCP工具

事件查询

  • get_events_today -获取今天的所有活动
  • get_tomorrow_events -获取明天的活动
  • get_week_events -获取本周活动
  • get_month_events -获取本月活动
  • get_upcoming_events -获取即将到来的活动（未来7天）
  • get_events_on_date -获取特定日期的事件
  • get_events_between_dates -获取日期范围内的事件
  • get_events_after_date -获取特定日期后的事件
  • search_calendar_events -按关键字搜索事件

冲突检测

  • get_calendar_conflicts -检测日历之间的日程安排冲突

饲料管理

  • refresh_calendar_feeds -手动刷新所有订阅源
  • get_calendar_info -获取有关已配置提要的信息
  • get_calendar_feeds -列出所有已配置的订阅源

注： 日历订阅源是通过以下方式配置的 ICAL_FEED_CONFIGS 环境变量。要添加或删除提要，请更新配置并重新启动服务器。

服务器管理

  • get_current_datetime -获取配置时区中的当前日期/时间
  • get_server_status -检查服务器运行状况
  • get_server_config -查看服务器配置

缓存管理（如果配置了Redis）

  • get_cache_stats -查看缓存性能指标
  • get_cache_info -查看Redis服务器信息
  • clear_cache -清除缓存数据
  • reset_cache_stats -重置缓存统计信息

安全

最佳实践

1.生成强大的API密钥：

openssl rand -base64 32  # Minimum 32 bytes recommended

2.在生产中使用HTTPS：

  • 配置TLS/SSL证书
  • 在入口中启用SSL重定向
  • 使用证书管理器自动续订

3.安全存储：

  • ✅ 存储在环境变量或Docker secrets中
  • ✅ 使用外部秘密管理（Vault、AWS Secrets Manager）
  • ✅ 加密静态秘密
  • ❌ 从不承诺版本控制
  • ❌ 从不记录API密钥

4.网络安全：

  • 使用防火墙规则限制访问
  • 考虑使用具有额外身份验证的反向代理
  • 使用有效的SSL证书启用HTTPS

5.费率限制：

  • 在反向代理级别配置速率限制
  • 使用nginx限速或fail2ban等工具

安全标头

服务器会自动添加安全标头：

  • X-Content-Type-Options: nosniff
  • X-Frame-Options: DENY
  • X-XSS-Protection: 1; mode=block
  • Referrer-Policy: no-referrer
  • Cache-Control: no-store, no-cache, must-revalidate, private

访问日志被禁用以防止API密钥泄漏。

关键点旋转

如果API密钥被泄露：

# 1. Generate new key and salt
NEW_KEY=$(openssl rand -base64 32)
NEW_SALT=$(openssl rand -base64 32)

# 2. Update .env.local file
echo "MCP_API_KEY=$NEW_KEY" >> .env.local
echo "MD5_SALT=$NEW_SALT" >> .env.local

# 3. Restart the Docker container
docker-compose down
docker-compose up -d

# 4. Get new endpoint URLs
python scripts/verify_auth.py --api-key "$NEW_KEY" --md5-salt "$NEW_SALT" --domain your-domain.com

# 5. Update MCP clients with new URLs

生产检查表

  • []生成了强MCP_API_KEY（32个字节以上）
  • []已配置MD5_SALT以增强安全性
  • []配置了有效证书的HTTPS/TLS
  • []在反向代理上启用SSL重定向
  • []已配置证书自动续订
  • []已配置防火墙规则
  • []在反向代理上配置了速率限制
  • []保护环境变量
  • []已配置监控和警报
  • []已制定关键轮换计划
  • []已测试备份和恢复
  • []已启用安全扫描
  • []定期审查访问日志

测试

使用Claude Desktop进行测试

“我的日历服务器的状态如何？” “我今天有什么活动？” “显示我下周的日程安排” “我这个月有日程安排冲突吗？”

测试HTTP端点

# Calculate endpoint URLs (with salt for enhanced security)
python scripts/verify_auth.py --api-key "$MCP_API_KEY" --md5-salt "$MD5_SALT" --domain localhost:8080 --no-https

# Or using environment variables
export MCP_API_KEY="your-api-key"
export MD5_SALT="your-salt"
python scripts/verify_auth.py --domain localhost:8080 --no-https

# Test health check (public endpoint)
curl http://localhost:8080/app/health

故障排除

“未配置iCalendar订阅源”

确保 ICAL_FEED_CONFIGS 使用有效的JSON正确设置。

订阅源未更新

  • 检查订阅源URL是否可公开访问
  • 验证URL是否返回有效的iCalendar数据
  • 尝试手动刷新： refresh_calendar_feeds 工具
  • 检查 REFRESH_INTERVAL 设置

时区问题

  • 确保日历提要包含时区信息
  • 服务器将时区标准化为UTC
  • 集 TIMEZONE 环境变量

JSON解析错误

  • 在中验证JSON格式 ICAL_FEED_CONFIGS
  • 在环境变量中JSON周围使用单引号
  • 正确转义双引号

容器无法启动

# Check container logs
docker logs calendar-mcp

# Common causes:
# - Missing ICAL_FEED_CONFIGS
# - Invalid JSON in ICAL_FEED_CONFIGS
# - Missing MCP_API_KEY (HTTP mode)

建筑

MCP Client
     ↓ (HTTP)
Docker Container
     ↓
MCP Server (FastMCP)
     └─ server_remote.py (HTTP API)
          ↓
Calendar Service (services/ical.py)
     ├─ Feed Parser (icalendar)
     ├─ Recurring Events (recurring-ical-events)
     └─ Auto-Refresh Timer
          ↓
     Optional Redis Cache (services/cache.py)
          ↓
iCalendar Feed URLs

演出

  • 自动缓存：缓存解析事件以减少处理
  • 背景刷新：无阻塞地馈送刷新
  • Redis支持：用于多实例部署的可选Redis
  • 高效解析：仅在提要更改时解析

发展

看 代理商.md 详细的开发文档，包括：

  • 建筑细部
  • 服务模式
  • 测试指导
  • 添加新功能
  • 常见陷阱

许可证

本项目按原样提供供个人使用。

支持

  • 问题：打开GitHub问题
  • 安全：私下报告漏洞
  • iCalendar规格: https://icalendar.org/

相关 MCP