MCP Server Google Calendar

🚀 基于MCP协议的Google日历服务器

这是一个基于Model Context Protocol（MCP）协议的Google Calendar集成服务器，支持像Claude Desktop这样的MCP客户端向Google Calendar添加日程安排，为用户提供便捷的日程管理体验。

🚀 快速开始

此服务器可助力MCP客户端与Google Calendar实现交互，为日程管理带来便利。下面为你介绍使用前的准备步骤。

✨ 主要特性

• 🔐 Google OAuth 2.0认证：保障用户账户安全。
• 📅 Google Calendar日程创建：方便用户添加日程。
• 🔍 支持按时间段查询Google Calendar日程：便于用户快速查找日程。
• 📆 获取当前日期：提供实时日期信息。
• ⏰ 支持韩国时区（KST）：满足特定时区用户需求。
• 🛠️ 详细的错误处理和日志记录：便于问题排查和系统维护。

📦 安装指南

克隆仓库

git clone [仓库地址]
cd mcp-server-google-calendar

安装依赖项

npm install

设置环境变量

创建.env文件，并添加以下内容：

GOOGLE_CLIENT_ID=你的客户ID
GOOGLE_CLIENT_SECRET=你的客户秘密

📚 详细文档

Google Cloud Console设置

1. 访问Google Cloud Console创建新项目。
2. 启用Google Calendar API。
3. 创建OAuth 2.0客户端ID：
   • 应用类型：选择"桌面应用"
   • 将生成的客户端ID和秘密添加到.env文件中。

Claude Desktop配置

1. 安装Claude Desktop
   • Claude Desktop下载
   • MCP功能仅在桌面应用程序中可用。
2. 配置MCP服务器 创建或编辑~/Library/Application Support/Claude/claude_desktop_config.json文件，添加以下内容：

   {
     "mcp-server-google-calendar": {
       "command": "/usr/local/bin/node",
       "args": ["/{绝对路径}/mcp-server-google-calendar/dist/main.js"],
       "env": {
         "GOOGLE_CLIENT_ID": "你的客户ID",
         "GOOGLE_CLIENT_SECRET": "你的客户秘密"
       }
     }
   }
   

3. 启动Claude Desktop后，访问设置中的"MCP服务"选项卡启用此新服务。

可用工具

• 📅 日历管理：创建、读取、更新和删除日程安排。
• ⏱️ 时间查询：获取当前日期和时间（支持KST）。
• ⏰ 提醒功能：设置和管理提醒事项。
• 🔄 多端同步：确保不同设备之间的日程同步。

调试

1. 开发者工具启用：

   echo '{"allowDevTools": true}' > ~/Library/Application\ Support/Claude/developer_settings.json
   

2. 在开发者模式下访问Command-Option-Shift-i打开调试工具。

错误处理

服务器在遇到以下情况时会返回适当的错误信息：

• 需要Google认证时
• 时间格式错误时
• 必需参数缺失时
• Google Calendar API调用失败时

日志记录

服务器使用Pino日志器记录以下信息：

• 服务器启动和关闭
• 工具调用及响应
• 认证流程
• 错误和异常情况

开发环境配置

1. TypeScript构建

npm run build

2. 启动开发模式（自动重启）

npm run dev

3. 代码检查

npm run lint

问题解决

服务器连接问题

• 检查Claude Desktop日志
• 确认服务器进程是否运行
• 核对环境变量设置
• 确保使用绝对路径

认证问题

• 检查Google Cloud Console中API是否已启用
• 重新确认客户端ID和秘密
• 确认OAuth同意屏幕设置

📄 许可证

本项目采用MIT License进行授权。