Google Calendar MCP Server

一个与Google日历集成的模型上下文协议（MCP）服务器，使用TypeScript构建。

特性

• 使用OAuth 2.0认证无缝集成Google日历
• 持久化令牌存储以实现自动认证
• 列出并管理日历，提供全面的事件操作
• 创建、读取、更新和删除日历事件
• 获取指定日期之间的日历事件
• 提供Server-Sent Events (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控制台
2. 创建新项目或选择现有项目
3. 启用Google Calendar API：
   • 导航到“APIs & Services” > “库”
   • 搜索“Google Calendar API”
   • 点击“启用”
4. 配置OAuth同意屏幕：
   • 转到“APIs & Services” > “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

使用方法

启动服务器

使用标准WebSocket启动：

npx -y mcp-google-calendar

使用Server-Sent Events (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控制台中撤销它们
• 该令牌授予访问您的Google日历数据的权限

许可证

本项目根据MIT许可证授权 - 详情见LICENSE文件。

贡献

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

1. 分叉仓库
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