谷歌日历MCP服务器
模型上下文协议（MCP）服务器，与谷歌日历智能集成，为人工智能模型提供上下文感知响应。该服务器分析用户查询，获取相关日历数据，并将其格式化为简洁的上下文，以增强AI助手的功能。
概述
谷歌日历MCP服务器充当“智能上下文引擎”，它：
- 截距 用户查询日历信息
- 分析 查询以了解需要什么日历上下文
- 获取 来自Google日历API的相关数据
- 组装 将数据转换为格式化的“上下文包”
- 交付 用于超相关响应的AI模型的上下文
特性
查询分析功能
- 检测时间参考（今天、明天、下周、特定日期）
- 识别意图类型（可用性检查、计划摘要、冲突检测）
- 从自然语言中提取日期/时间参数
日历数据获取
- 即将发生的事件（接下来的N个事件，特定日期的事件）
- 活动详细信息（标题、时间、与会者、地点、描述）
- 可用性窗口
- 冲突检测
- 会议纪要
上下文格式
- 简明的活动总结
- 可用性状态
- 冲突警报
- 时间感知格式
数据源
此MCP服务器连接到 谷歌日历API 以获取日历事件并基于用户的日程提供个性化上下文。
先决条件
- Python 3.10或更高版本
- 启用Google日历API的Google云项目
- 来自谷歌云控制台的OAuth 2.0凭据
安装
- 克隆或下载此存储库
- 创建虚拟环境 （推荐）：
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate- 安装依赖项:
pip install -r requirements.txt- 设置Google日历API凭据:
a.前往 谷歌云控制台
b.创建新项目或选择现有项目
c.启用Google日历API：
- 导航到“API和服务”>“库” - 搜索“Google日历API” - 点击“启用”
d.配置OAuth同意屏幕：
- 转到“API和服务”>“OAuth同意屏幕” - 选择“外部”（除非您有Google Workspace帐户） - 填写所需信息 - 添加作用域： https://www.googleapis.com/auth/calendar.readonly - 关键的：在“测试用户”下，单击“添加用户”并添加您的电子邮件地址(darshilrayjada4154@gmail.com) - 备注：如果不将电子邮件添加为测试用户，则在尝试身份验证时将收到“错误403:access_denied”
e.创建OAuth 2.0凭据：
- 转到“API和服务”>“凭据” - 点击“创建凭据”>“OAuth客户端ID” - 选择“桌面应用程序”作为应用程序类型 - 下载凭据JSON文件
f.放置凭证文件：
- 将下载的文件重命名为 credentials.json - 把它放在 config/ 目录 - 文件应位于： config/credentials.json
g。 配置授权重定向URI （重要）：
- 返回“API和服务”>“凭据” - 点击您的OAuth 2.0客户端ID（您刚刚创建的ID） - 在“授权重定向URI”下，单击“添加URI” - 添加以下重定向URI： - http://localhost:8080/ - http://localhost:8081/ - http://localhost/ - http://127.0.0.1:8080/ - 点击“保存” - 备注：这一步至关重要！如果没有这些重定向uri，您将收到“redirect_uri_mismatch”错误。
- 配置环境变量 （可选）：
cp .env.example .env
# Edit .env if you need to customize paths用法
运行服务器
启动MCP服务器：
python main.py或者：
python -m src.server首次运行时，服务器将：
- 打开浏览器窗口进行Google OAuth身份验证
- 要求您登录并授予日历访问权限
- 保存身份验证令牌以备将来使用
MCP工具
服务器提供以下工具：
1. get_calendar_context
分析查询并返回格式化日历上下文的主要工具。
示例提示：
- “我明天下午两点有空吗？”
- “这周我有什么会议？”
- “下周一我有什么冲突吗？”
2. check_availability
检查用户是否在特定日期和时间可用。
参数：
date：检查日期（YYYY-MM-DD格式或自然语言，如“明天”）time：检查时间（HH:MM格式或自然语言，如“下午2点”）-可选duration_hours：时间段的持续时间（以小时为单位）（默认值：1.0）
例子：
check_availability(date="2024-12-15", time="14:00", duration_hours=1.0)3. get_upcoming_events
获取即将到来的日历事件。
参数：
days：展望未来的天数（默认值：7）max_results：要返回的最大事件数（默认值：10）
例子：
get_upcoming_events(days=7, max_results=10)4. detect_conflicts
检测特定日期的日程安排冲突。
参数：
date：检查日期（YYYY-MM-DD格式或自然语言，如“明天”）
例子：
detect_conflicts(date="2024-12-15")示例用例
示例1：可用性检查
查询“我明天下午2点有空吗？”
上下文：“用户明天的日历显示：下午1:00-2:30的“团队会议”。用户下午2点没有空。”
AI响应：“不，看起来你明天下午1点到2点30分有一个‘团队会议’，所以你下午2点没有空。”
示例2：进度汇总
查询：“我这周有什么会议？”
上下文：“未来7天的日程安排：12月9日星期一-‘项目审查’（上午10:00-上午11:00），‘客户电话’（下午3:00-下午4:00）；12月10日星期二-‘站立’（上午9:00-上午9:30）”
AI响应：“本周你有：周一上午10点进行‘项目审查’，下午3点进行‘客户拜访’；周二上午9点进行‘站立’。”
示例3：冲突检测
查询：“下周一我有什么冲突吗？”
上下文“12月16日星期一没有发现冲突。您安排了2个活动：“午餐会”（中午12:00-下午1:00）；“代码审查”（下午4:00-5:00）
AI响应：“下周一未检测到冲突。您有两个活动：中午12点的“午餐会”和下午4点的“代码审查”。”
项目结构
mcp-server/
├── src/
│ ├── __init__.py
│ ├── server.py # Main MCP server implementation
│ ├── query_analyzer.py # Query parsing and intent detection
│ ├── calendar_client.py # Google Calendar API wrapper
│ ├── context_formatter.py # Data formatting and summarization
│ └── utils.py # Helper functions
├── config/
│ ├── credentials.json # Google OAuth credentials (not in repo)
│ └── credentials.json.example # Example credentials file
├── requirements.txt
├── README.md
├── .env.example # Environment variables template
└── .gitignore错误处理
该服务器包括全面的错误处理功能，用于：
- API速率限制：检测并报告速率限制错误，并显示有用消息
- 身份验证失败：为重新身份验证提供明确的指导
- 网络超时：优雅地处理连接问题
- 日期/时间解析无效：解析失败时恢复默认值
- 缺少凭证：清除缺少配置文件的错误消息
安全说明
- 永不承诺
credentials.json或token.json到版本控制 - 这
.gitignore文件配置为排除敏感文件 - OAuth令牌存储在本地并自动刷新
- 服务器仅请求对您的日历进行只读访问
故障排除
身份验证问题
重定向URI不匹配错误（错误400）
如果您看到类似“redirect_uri_mismatch”或“错误400:redirect_uri \_mismatch“的错误：
- 首选 谷歌云控制台
- 导航到： API和服务 > 凭证
- 点击您的OAuth 2.0客户端ID
- 在...之下 “授权重定向URI”，添加：
- http://localhost:8080/ - http://localhost:8081/ - http://localhost/ - http://127.0.0.1:8080/
- 点击 “保存”
- 再次尝试身份验证
拒绝访问错误（错误403）
如果您看到“错误403:access_denied”或“MCP Desktop尚未完成谷歌验证过程”：
- 首选 谷歌云控制台
- 导航到： API和服务 > OAuth同意屏幕
- 向下滚动到 “测试用户” 章节
- 点击 “添加用户”
- 添加您的电子邮件地址（您用于登录的电子邮件地址）
- 点击 “添加”
- 再次尝试身份验证
一般身份验证问题
- 确保
credentials.json是在config/目录 - 删除
config/token.json如果看到身份验证错误，请重新进行身份验证 - 验证OAuth同意屏幕是否配置正确
- 重要：确保您已在OAuth同意屏幕中将您的电子邮件添加为测试用户（如果应用程序处于测试模式，则需要）
API错误
- 检查Google日历API是否已在您的Google Cloud项目中启用
- 验证您是否已授予必要的权限
- 确保您的Google帐户有活动日历
导入错误
- 确保安装了所有依赖项：
pip install -r requirements.txt - 验证您使用的是Python 3.10或更高版本
- 检查您是否从项目根目录运行
发展
运行测试
# Add your test commands here when tests are implemented
python -m pytest tests/贡献
- 分叉存储库
- 创建要素分支
- 进行更改
- 提交拉取请求
许可证
该项目是为“构建自己的MCP挑战赛”而创建的。
致谢
- 使用 模型上下文协议
- Google日历API集成
- MCP Python SDK
联系
如有疑问或问题，请在存储库中打开问题。