AI导哈

日历分析MCP服务器

一个用于日历分析的MCP服务器，能够分析日历事件、分类事件、跟踪能量水平并生成详细的Markdown报告。

  • by sergivalverde
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 sergivalverde/calendar-mcp

使用说明

日历分析MCP服务器

充当日历分析执行助理的MCP（模型上下文协议）服务器。它分析日历事件，将其分为生产力类别，跟踪能源水平，并生成带有表格和图表的全面降价报告。

特性

  • 自然语言查询：问“分析我上周的日历”或“显示11月的时间分布”之类的问题
  • 智能事件分类：使用基于优先级的规则将事件自动分类为13个生产力类别
  • 能量水平跟踪：将E1-E4能源标记与主要活动相匹配，以获得生产力见解
  • 综合报告：生成显示时间分布和模式的表格和美人鱼饼图
  • 可配置规则：自定义分类关键字、排除模式和团队域
  • macOS集成：使用icalBuddy从macOS日历应用程序中提取事件

安装

先决条件

  1. Python 3.9+ 随着 uv 包管理器
  2. icalBuddy：通过Homebrew安装：
    brew install ical-buddy

安装MCP服务器

# Clone or download the project
cd calendar-mcp

# Install dependencies and create virtual environment
uv sync

# The server is now ready to use

用法

基本用法

MCP服务器提供 query_calendar 接受自然语言查询的工具。以下是一些示例：

# Analyze last week
"Analyze my calendar for last week"

# Check yesterday's energy levels
"What were my energy levels yesterday?"

# Monthly overview
"Show time distribution for November"

# Recent activity
"Analyze my calendar for the last 3 days"

日期范围解析

服务器自动解析自然语言中的日期范围：

  • 今天：“今天”，“今天”
  • 昨天：“昨天”
  • 本周：“本周”、“当前周”（周一至今天）
  • 上周：“上周”、“上周”（前周一至周日）
  • 本月：“本月”、“当月”（1日至今天）
  • 上个月：“上月”、“上月”
  • 最近N天：“过去7天”，“过去3天”
  • 过去N周：“过去两周”
  • 过去N个月：“过去3个月”
  • 具体月份：“十一月”，“去年十一月”
  • 默认：过去7天（如果未检测到日期范围）

日历访问配置

MCP服务器使用 icalBuddy 访问您的macOS日历数据。默认情况下，它会访问您的用户帐户有权读取的所有日历。

日历访问的工作原理

  1. 系统集成：icalBuddy使用与Calendar.app相同的macOS日历权限
  2. 默认行为：如果没有配置特定的日历，它将查询所有可访问的日历
  3. 安全：只有您在Calendar.app中有权访问的日历可用

检查可用日历

您可以列出可用的日历：

icalBuddy calendars

配置特定日历

编辑 src/calendar_mcp/config.json 将分析限制在特定日历上：

{
  "calendar": {
    "calendars": ["Work", "Personal Projects"]
  },
  "classification": {
    ...
  }
}

如果 calendars 是 null 使用所有日历。

事件分类配置

服务器使用 config.json 用于自定义分类规则的文件。文件位于 src/calendar_mcp/config.json.

配置选项

{
  "calendar": {
    "calendars": null
  },
  "classification": {
    "excluded_titles": ["Blocked ✋", "Blocked", "Busy", "Tentative"],
    "personal_patterns": ["Helena", "Lunch - Helena"],
    "all_day_exclusion": true,
    "team_domains": ["tensormedical.ai"],
  "information_processing_keywords": ["email", "processing"],
  "recruiting_keywords": ["interview", "hiring"],
  "reading_keywords": ["reading", "anki", "study"],
  "team_keywords": ["1:1", "sync", "weekly"],
  "investor_relations_keywords": ["investment", "investor", "deck"],
  "strategy_keywords": ["strategy", "planning", "roadmap"],
  "sales_marketing_keywords": ["demo", "proposal", "pitch"],
  "engineering_keywords": ["review", "integration", "code"],
  "operations_keywords": ["audit", "legal", "HR"],
  "exercise_keywords": ["exercise", "workout", "run"],
  "meditation_keywords": ["meditation", "mindfulness"],
  "github_repos_engineering": ["research", "brain"],
  "github_repos_strategy": ["brain"]
}

自定义分类

  • 团队域名：添加公司域以正确分类团队会议
  • 排除模式：添加要排除的个人事件标题或模式
  • 类别关键字：为每个类别自定义关键字
  • GitHub仓库：指定哪些存储库表示工程工作与战略工作

事件分类

使用基于优先级的系统将事件分为13类：

优先顺序

  1. 显式类别匹配：事件标题与类别名称匹配
  2. 外部客户端：非团队参与者的活动→ 销售/网络
  3. 投资者：投资/筹资关键词→ 投资者关系
  4. 招聘：招聘/面试关键词→ 招聘
  5. 团队会议：@团队域与会者→ Team
  6. 技术工作：代码/产品关键字→ 工程
  7. GitHub链接：基于存储库的分类
  8. 策略：规划/路线图关键字→ 策略
  9. 其他类别：剩余类别的关键字匹配

分类

  • 信息处理：电子邮件处理、通信任务
  • 招聘：面试、招聘活动
  • 阅读：学习课程、论文阅读
  • 团队：与同事的会议（@team域）
  • 投资者关系：筹资、投资者会议
  • 策略：长期规划、路线图
  • 销售与营销：演示、提案、客户会议
  • 网络：外部连接、事件
  • 工程：代码审查、技术工作
  • 运营：行政、法律、人力资源任务
  • 锻炼：体育活动、锻炼
  • 冥想：正念活动
  • 其他：非分类生产性工作

能量水平跟踪

使用与主要事件重叠的特殊“E”事件来跟踪能量水平：

  • E1/L1：能量非常低
  • E2/L2：低能耗
  • E3/L3：高能量
  • E4/L4：天才区

能量标记可以包括描述性文本：“E4——这段对话很有活力”

报告格式

服务器生成全面的降价报告，包括：

1.原始事件表

显示所有分类事件，包括时间、类别和能量水平。

2.每日汇总表

每天花费的时间和能量水平百分比的前3个类别。

3.类别分布

使用美人鱼饼图按类别进行时间细分。

4.能源分配

用美人鱼饼图按能量水平进行时间分解。

输出格式化

  • 小时：带逗号分隔符的十进制格式（1.5而非1.5）
  • 日期：dd/mm/yyyy格式
  • 泰晤士报：HH:MM 24小时格式
  • 百分比：四舍五入到小数点后1位
  • 图表：美人鱼饼图语法

故障排除

icalBuddy问题

错误: icalBuddy not found

  • 安装icalBuddy： brew install ical-buddy

未找到事件

  • 检查日历应用程序权限
  • 确保在icalBuddy中启用日历
  • 试着跑步 icalBuddy eventsToday 手动地

分类问题

错误类别的事件

  • 检查 config.json 关键字列表
  • 为您的工作模式添加自定义关键字
  • 如果公司电子邮件格式更改，则更新团队域

个人活动包括

  • 将排除模式添加到 personal_patterns 在配置中
  • 检查 excluded_titles 列表

配置问题

配置未加载

  • 确保 config.json 是有效的JSON
  • 检查文件权限
  • 如果文件丢失，将自动创建默认文件

发展

项目结构

calendar-mcp/
├── pyproject.toml          # uv configuration
├── src/calendar_mcp/
│   ├── __init__.py
│   ├── server.py           # MCP server
│   ├── models.py           # Data models
│   ├── calendar_extractor.py # icalBuddy integration
│   ├── classifier.py       # Event classification
│   ├── energy_tracker.py   # Energy level matching
│   ├── report_generator.py # Markdown report generation
│   ├── config.py           # Configuration management
│   └── config.json         # Default configuration
└── README.md

运行测试

uv run pytest

建筑

uv build

许可证

这个项目是开源的。有关详细信息，请参阅LICENSE文件。

相关 MCP