Google Calendar MCP 服务器

一个与 Google Calendar 集成的模型上下文协议 (MCP) 服务器，使用 TypeScript 构建。

特性

• 使用 OAuth 2.0 身份验证无缝集成 Google Calendar
• 持久化令牌存储，实现自动身份验证
• 列出和管理日历，并提供全面的事件操作
• 创建、读取、更新和删除日历事件
• 获取指定日期之间的日历事件
• 用于实时更新的服务器发送事件 (SSE) 传输选项
• 与 Claude 和其他 MCP 兼容的 AI 助手简单集成

安装

npm install -g mcp-google-calendar

或者直接运行：

npx -y mcp-google-calendar

前提条件

1. Node.js (v16 或更高版本)
2. Google Cloud Platform 帐户
3. 启用 Google Calendar API
4. OAuth 2.0 凭据

设置

1. Google Cloud 配置

1. 转到 Google Cloud Console
2. 创建一个新项目或选择一个现有项目
3. 启用 Google Calendar API：
   • 导航到“API 和服务”>“库”
   • 搜索“Google Calendar API”
   • 点击“启用”
4. 配置 OAuth 同意屏幕：
   • 转到“API 和服务”>“OAuth 同意屏幕”
   • 选择“外部”用户类型（或 Google Workspace 的“内部”）
   • 填写所需信息：
     • 应用名称：mcp-calendar
     • 用户支持电子邮件：（您的电子邮件）
     • 开发者联系信息：（您的电子邮件）
   • 添加范围：
     • 点击“添加或删除范围”
     • 查找并选择“https://www.googleapis.com/auth/calendar.events”
     • 将您的电子邮件添加为测试用户
   • 完成设置
5. 创建 OAuth 凭据：
   • 转到“凭据”
   • 点击“创建凭据”>“OAuth 客户端 ID”
   • 选择“桌面应用”作为应用程序类型
   • 命名它（例如，“MCP Calendar Desktop Client”）
   • 下载 JSON 文件并另存为项目目录中的 credentials.json

2. 环境配置

在项目根目录中创建一个 .env 文件：

# 服务器配置
PORT=3420

# Google Calendar API 配置
CREDENTIALS_PATH=./credentials.json

用法

启动服务器

使用标准 WebSockets 启动：

npx -y mcp-google-calendar

使用服务器发送事件 (SSE) 启动：

npx -y mcp-google-calendar --sse

与 Claude Desktop 配合使用

将此添加到您的 claude_desktop_config.json：

{
   "mcpServers": {
      "mcp-google-calendar": {
         "command": "npx",
         "args": ["-y", "mcp-google-calendar"],
         "env": {
            "CREDENTIALS_PATH": "/path/to/your/credentials.json"
         }
      }
   }
}

身份验证过程

首次运行服务器时：

1. 将自动打开一个浏览器窗口
2. 使用您的 Google 帐户登录
3. 授予请求的日历权限
4. 身份验证令牌将保存到 token.json

在后续启动时：

• 服务器自动使用保存的令牌
• 除非令牌过期，否则不需要浏览器交互

可用工具

工具	描述
list_calendars	获取所有可用日历
list_calendar_events	检索指定日期之间的事件
create_calendar_event	向您的日历添加新事件
get_calendar_event	获取特定事件的详细信息
edit_calendar_event	修改现有日历事件
delete_calendar_event	从您的日历中删除事件

开发

克隆并设置项目：

git clone https://github.com/am2rican5/mcp-google-calendar.git
cd mcp-google-calendar
npm install

构建项目：

npm run build

在开发模式下运行：

npm start

安全注意事项

⚠️ 重要安全警告 ⚠️

• credentials.json 和 token.json 包含敏感的身份验证信息
• 永远不要将这些文件提交到版本控制或公开分享它们
• 每个用户都应该创建自己的 OAuth 凭据
• 如果您怀疑凭据泄露，请立即在 Google Cloud Console 中撤销它们
• 该令牌授予对您的 Google Calendar 数据的访问权限

许可证

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参见 LICENSE 文件。

贡献

欢迎贡献！ 请随时提交 Pull Request。

1. Fork 存储库
2. 创建您的功能分支 (git checkout -b feature/amazing-feature)
3. 提交您的更改 (git commit -m 'Add some amazing feature')
4. 将分支推送到远程仓库 (git push origin feature/amazing-feature)
5. 打开一个 Pull Request