金大哥 - Google-Calendar-MCP-Server MCP 详情

article

README

🚀 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（必需）：要更新的活动 ID
summary（可选）：新的活动标题
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 规范。
在本仓库中创建一个问题。

Google-Calendar-MCP-Server