JinDaGe - mcp-server-google-calendar MCP Details

article

README

🚀 基于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设置

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

Claude Desktop配置

安装Claude Desktop
- Claude Desktop下载
- MCP功能仅在桌面应用程序中可用。

配置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": "你的客户秘密"
    }
  }
}

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

可用工具

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

调试

开发者工具启用：

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

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

错误处理

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

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

日志记录

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

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

开发环境配置

TypeScript构建

npm run build

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

npm run dev

代码检查

npm run lint

问题解决

服务器连接问题

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

认证问题

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

📄 许可证

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

mcp-server-google-calendar