MCP Google Calendar Server

MCP Google Calendar 服务

基于 MCP（Model Context Protocol）的 Google Calendar 集成服务。支持从 Claude Desktop 等 MCP 客户端向 Google Calendar 添加日程。

功能

• Google OAuth 2.0 认证
• 向 Google Calendar 添加日程
• 查询 Google Calendar 日程（支持按时间段查询）
• 查询今天的日期
• 支持韩国标准时间（KST）
• 详细的错误处理和日志记录

安装方法

1. 克隆存储库

git clone [repository-url]
cd mcp-server-google-calendar

2. 安装依赖

npm install

3. 设置环境变量 创建 .env 文件并添加以下内容：

GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_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 功能仅可在桌面应用中使用，无法在 Web 版本中使用。

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": "your_client_id",
         "GOOGLE_CLIENT_SECRET": "your_client_secret",
         "NODE_ENV": "production"
       }
     }
   }
   

   配置项说明：

   • command：Node.js 可执行文件的绝对路径
   • args：要运行的 JavaScript 文件的绝对路径（TypeScript 构建后生成的文件）
   • cwd：项目工作目录的绝对路径
   • env：环境变量设置
     • GOOGLE_CLIENT_ID：在 Google Cloud Console 中创建的客户端 ID
     • GOOGLE_CLIENT_SECRET：在 Google Cloud Console 中创建的客户端密钥
     • NODE_ENV：运行环境设置

   注意：以上示例根据当前安装路径编写。在其他环境中，需要修改为对应环境的绝对路径。

3. 构建和准备

   # TypeScript 컴파일
   npm run build
   
   # Node.js 실행 파일 위치 확인
   which node
   

4. 重启 Claude Desktop

   • 重启 Claude Desktop 以应用设置。
   • 点击状态图标可查看服务连接状态。
   • 如果出现连接问题，请检查日志。

可用工具

googleAuthLogin

执行 Google Calendar API 认证。

// Claude에서 사용 예시
tool("googleAuthLogin");

addCalendarEvent

向 Google Calendar 添加新日程。

// Claude에서 사용 예시
tool("addCalendarEvent", {
  title: "회의",
  startTime: "2024-03-20 15:00", // YYYY-MM-DD HH:mm 형식
  duration: "60", // 분 단위
});

listCalendarEvents

查询特定时间段内的 Google Calendar 日程。

// Claude에서 사용 예시
tool("listCalendarEvents", {
  period: "2024-03-20~2024-03-27", // YYYY-MM-DD~YYYY-MM-DD 형식
});

getTodayDate

以 YYYY-MM-DD 格式返回今天的日期。

// Claude에서 사용 예시
tool("getTodayDate");

调试

查看日志

# 실시간 로그 확인
tail -n 20 -F ~/Library/Logs/Claude/mcp*.log

启用开发者工具

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. 运行 lint 检查

npm run lint

故障排除

1. 服务连接问题

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

2. 认证问题

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

许可证

MIT License