Google Calendar MCP Server

📅 一个基于 Model Context Protocol (MCP) 的 Google Calendar 集成服务器

让 AI 助手能够访问和查询您的 Google 日历数据

✨ 功能特性

• 🔐 安全的 OAuth2 认证 - 使用 Google 官方授权流程
• 📆 日历查询 - 按日期查询日历事件
• 🤖 AI 集成 - 与 Cursor 等 AI 工具无缝集成
• 🔄 自动刷新 - Token 自动刷新，无需重复授权
• 🎯 简单易用 - 两种授权方式，适合不同使用场景

📋 前置要求

• Node.js 18+
• Google 账户
• Cursor 编辑器（或其他支持 MCP 的 AI 工具）

🚀 快速开始

步骤 1: 获取 Google OAuth2 凭据

1. 访问 Google Cloud Console
2. 创建新项目或选择现有项目
3. 启用 Google Calendar API：
   • 导航至 API 和服务 → 库
   • 搜索并启用 Google Calendar API
4. 创建 OAuth2 凭据：
   • 导航至 API 和服务 → 凭据
   • 点击 创建凭据 → OAuth 客户端 ID
   • 应用类型：桌面应用
   • 复制 客户端 ID 和 客户端密钥

步骤 2: 获取授权（推荐方式）

使用仓库中的脚本

node get-token.js

授权脚本会：

1. 自动打开浏览器授权页面
2. 启动本地服务器接收回调
3. 生成配置信息，直接复制到 mcp.json

💡 提示：运行脚本前，请先在 get-token.js 中填入您的 Client ID 和 Client Secret

步骤 3: 配置 MCP

编辑 ~/.cursor/mcp.json（如果不存在则创建）：

{
  "mcpServers": {
    "calendar-data": {
      "command": "npx",
      "args": ["-y", "@boom-10/google-calendar-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "你的客户端ID.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "你的客户端密钥",
        "GOOGLE_REFRESH_TOKEN": "从授权脚本获取的refresh_token",
        "CALENDAR_ID": "你的邮箱@gmail.com"
      }
    }
  }
}

⚠️ 重要提示：

• 将路径替换为实际的绝对路径
• 不要将包含凭据的配置文件上传到公开仓库

步骤 4: 重启 Cursor

重启 Cursor 编辑器以加载 MCP 配置。

💬 使用示例

授权完成后，您可以在 Cursor 中直接询问：

今天有什么安排？

查询 2025-11-05 的日历

本周有哪些会议？

AI 助手会自动调用日历 API 并返回结果。

🛠️ 可用工具和命令

MCP 工具

| 工具名称 | 功能描述 | | ------------------------- | ---------------------- | | getMyCalendarDataByDate | 查询指定日期的日历事件 |

CLI 命令

安装包后可用的命令行工具：

| 命令 | 功能描述 | | ---------------------- | ------------------------------ | | google-calendar-mcp | 启动 MCP 服务器（用于 Cursor） | | google-calendar-auth | 运行 OAuth 授权工具获取 Token |

🔧 手动授权方式（备选）

如果自动化脚本无法使用，可以采用手动方式：

1. 在 Cursor 中要求 AI 生成授权 URL
2. 在浏览器中访问该 URL 并登录 Google 账户
3. 授权后复制授权码
4. 要求 AI 使用授权码保存 token

完成后会生成 token.json 文件。

🐛 故障排除

问题：授权后仍然无法访问日历

解决方案：

• 确认 CALENDAR_ID 设置为正确的邮箱地址
• 检查 Google Cloud Console 中 Calendar API 是否已启用
• 重启 Cursor 编辑器

问题：Token 过期或无效

解决方案：

• 删除 token.json 文件
• 重新运行 node get-token.js 获取新 token
• 更新 mcp.json 中的 GOOGLE_REFRESH_TOKEN

问题：重定向 URI 不匹配

解决方案：

• 在 Google Cloud Console 的 OAuth 客户端设置中
• 确保添加了 http://localhost:3000/oauth2callback

问题：端口 3000 已被占用

解决方案：

• 编辑 get-token.js，将端口改为其他值（如 3001）
• 同时更新 Google Cloud Console 中的重定向 URI

📁 项目结构

google-calendar-mcp/
├── index.ts           # MCP 服务器主文件
├── get-token.js       # OAuth 授权工具脚本
├── package.json       # 项目依赖配置
├── tsconfig.json      # TypeScript 配置
└── README.md          # 项目文档

🔒 安全性建议

• ✅ 不要将 token.json 上传到 Git 仓库
• ✅ 不要分享您的客户端密钥和 refresh token
• ✅ 定期检查 Google 账户的已授权应用
• ✅ 使用最小权限原则（当前仅请求只读权限）

📄 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📞 支持

如有问题，请查看：

• MCP 官方文档
• Google Calendar API 文档