🚀 Google Calendar MCP Server
Google Calendar MCP Server 是一个基于模型上下文协议（MCP）的服务器，它具备全面的 Google Calendar 集成能力。该服务器允许 AI 助手和应用程序通过标准化协议与 Google Calendar 进行交互。
🚀 快速开始
运行服务器
# 启动编译后的服务器
npm start
# 或者在开发模式下运行
npm run dev
与 MCP 客户端集成
将此服务器添加到您的 MCP 客户端配置中：
{
"servers": {
"google-calendar": {
"type": "stdio",
"command": "node",
"args": ["./dist/index.js"]
}
}
}
对于使用 MCP 扩展的 VS Code，将以下内容添加到 .vscode/mcp.json 中：
{
"servers": {
"google-calendar-mcp-server": {
"type": "stdio",
"command": "node",
"args": ["./dist/index.js"]
}
}
}
认证设置
- 创建服务账户：
- 访问 Google Cloud Console。
- 导航到“IAM & Admin”>“服务账户”。
- 创建一个新的服务账户。
- 下载 JSON 密钥文件。
- 共享日历访问权限：
- 打开 Google Calendar。
- 进入日历设置。
- 与服务账户的电子邮件共享您的日历。
- 授予“对活动进行更改”的权限。
- 配置环境：
- 将 JSON 密钥文件放在您的项目目录中。
- 使用正确的路径更新
.env文件。
✨ 主要特性
- 列出活动：从 Google Calendar 检索活动，并支持过滤选项。
- 创建活动：可完全自定义地创建新的日历活动。
- 更新活动：修改现有的日历活动。
- 删除活动：从日历中移除活动。
- 列出日历：获取经过身份验证的用户可用的日历。
- OAuth 认证：安全地访问 Google Calendar API。
📦 安装指南
前提条件
- Google Cloud 项目：在 Google Cloud Console 中创建一个项目。
- 启用 Google Calendar API：为您的项目启用日历 API。
- 服务账户：创建一个服务账户并下载 JSON 密钥文件。
安装步骤
- 克隆此仓库。
- 安装依赖项：
npm install - 复制环境文件并进行配置：
copy .env.example .env - 编辑
.env文件，设置您的 Google 服务账户密钥文件路径：GOOGLE_SERVICE_ACCOUNT_KEY_FILE=./path/to/your/service-account-key.json
构建项目
# 构建 TypeScript 代码
npm run build
# 开发模式，支持热重载
npm run dev
# 类型检查
npm run type-check
# 清理构建产物
npm run clean
💻 使用示例
list_events
使用各种过滤选项从 Google Calendar 检索活动。
参数：
calendarId（可选）：日历 ID（默认值："primary"）timeMin（可选）：活动开始时间的下限（RFC3339 时间戳）timeMax（可选）：活动开始时间的上限（RFC3339 时间戳）maxResults（可选）：活动的最大数量（默认值：250）singleEvents（可选）：展开重复活动（默认值：true）orderBy（可选）：按“startTime”或“updated”对活动进行排序
create_event
在 Google Calendar 中创建一个新的活动。
参数：
calendarId（可选）：日历 ID（默认值："primary"）summary（必需）：活动标题description（可选）：活动描述start（必需）：包含 dateTime 和可选 timeZone 的开始日期/时间对象end（必需）：包含 dateTime 和可选 timeZone 的结束日期/时间对象location（可选）：活动地点attendees（可选）：包含电子邮件和显示名称的参与者对象数组recurrence（可选）：用于重复活动的 RRULE 字符串数组
update_event
更新现有的日历活动。
参数：
calendarId（可选）：日历 ID（默认值："primary"）eventId（必需）：要更新的活动 IDsummary（可选）：新的活动标题description（可选）：新的活动描述start（可选）：新的开始日期/时间end（可选）：新的结束日期/时间location（可选）：新的活动地点attendees（可选）：新的参与者列表
delete_event
从 Google Calendar 中删除一个活动。
参数：
calendarId（可选）：日历 ID（默认值："primary"）eventId（必需）：要删除的活动 ID
list_calendars
列出经过身份验证的用户可用的 Google 日历。
参数：
minAccessRole（可选）：最小访问角色过滤器showDeleted（可选）：包括已删除的日历（默认值：false）showHidden（可选）：包括隐藏的日历（默认值：false）
📚 详细文档
项目结构
src/
├── index.ts # 主要的 MCP 服务器实现
├── types/ # TypeScript 类型定义
└── utils/ # 实用函数
.env.example # 环境变量模板
tsconfig.json # TypeScript 配置
package.json # Node.js 依赖项和脚本
添加新工具
- 定义一个 Zod 模式用于输入验证。
- 创建一个 ToolSchema 定义。
- 实现异步处理函数。
- 在服务器中注册该工具。
- 添加全面的错误处理。
错误处理
所有工具都返回结构化响应：
// 成功响应
{
content: [{ type: "text", text: JSON.stringify(result) }]
}
// 错误响应
{
content: [{ type: "text", text: JSON.stringify(error) }],
isError: true
}
🔧 技术细节
安全注意事项
- 切勿将服务账户密钥提交到版本控制中。
- 对所有敏感配置使用环境变量。
- 实施适当的错误处理，避免信息泄露。
- 定期轮换服务账户密钥。
- 遵循 Google Cloud 的安全最佳实践。
贡献指南
- 分叉此仓库。
- 创建一个功能分支。
- 进行更改并进行适当的测试。
- 提交拉取请求。
📄 许可证
本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。
支持
如有问题和疑问：
- 查看 Google Calendar API 文档。
- 查看 MCP 规范。
- 在本仓库中创建一个问题。