内容
# Google 日历 MCP 服务器
用于管理 Google 日历事件的模型上下文协议（MCP）服务器。
## 功能
- 列出、创建、更新、删除和获取日历事件
- OAuth 2.0 和服务账户身份验证
- Docker 支持，方便部署
- MCP 客户端集成（Cursor，Claude Desktop）
## 快速开始
```bash
# 安装依赖
npm install
# 与 Google 身份验证
npm run auth
# 构建并运行
npm run build
npm start
```
Docker：请参阅 [DOCKER.md](DOCKER.md)
## 项目结构
```
googlecalendar-mcp/
├── src/
│ ├── index.ts # 主 MCP 服务器
│ └── auth-helper.ts # OAuth 身份验证助手
├── dist/ # 编译后的 JavaScript（生成）
├── .env # 环境变量（从 .env.example 创建）
├── package.json # Node.js 依赖项
├── tsconfig.json # TypeScript 配置
├── Dockerfile # Docker 构建配置
├── docker-compose.yml # Docker Compose 设置
├── docker-helper.sh # Docker 便捷脚本
├── README.md # 此文件
└── DOCKER.md # Docker 特定文档
```
## 先决条件
- Node.js 18+
- Google Cloud 项目，已启用日历 API
- OAuth 2.0 凭证
## 设置
### 1. 设置 Google 日历 API
#### 1.1 创建或选择项目
1. 访问 [Google Cloud 控制台](https://console.cloud.google.com/)
2. 点击页面顶部的项目下拉菜单
3. 您可以：
- **创建新项目**：点击“新项目”，输入项目名称（例如“Google 日历 MCP”），然后点击“创建”
- **选择现有项目**：从现有项目列表中选择
#### 1.2 启用 Google 日历 API
1. 在 Google Cloud 控制台中，导航到 **“API 和服务”>“库”** （或使用搜索栏）
2. 搜索 **“Google 日历 API”**
3. 点击搜索结果中的 **“Google 日历 API”**
4. 点击 **“启用”** 按钮
5. 等待 API 启用（通常需要几秒钟）
6. 您应该看到确认消息：“API 已启用”
**替代方法：**
- 您也可以直接通过此链接启用（将 `YOUR_PROJECT_ID` 替换为您的实际项目 ID）：
```
https://console.cloud.google.com/apis/library/calendar-json.googleapis.com?project=YOUR_PROJECT_ID
```
**故障排除：**
- 如果您看到类似“Google 日历 API 在项目 X 中尚未使用过或已禁用”的错误，请确保您已完成上述步骤
- 启用后，请等待几分钟，让更改在 Google 系统中传播
- 通过检查 **“API 和服务”>“已启用 API”** 来验证 API 是否已启用 - 您应该看到“Google 日历 API”列出
#### 1.3 创建 OAuth 2.0 凭证
1. 在 Google Cloud 控制台中，导航到 **“API 和服务”>“凭证”**
2. 如果这是您第一次，可能需要配置 OAuth 同意屏幕：
- 点击 **“配置同意屏幕”**
- 选择 **“外部”** （除非您有 Google Workspace，则选择“内部”）
- 填写必填信息：
- 应用名称：“Google 日历 MCP”（或您喜欢的任何名称）
- 用户支持电子邮件：您的电子邮件地址
- 开发人员联系信息：您的电子邮件地址
- 点击 **“保存并继续”** 完成步骤（您可以暂时跳过可选步骤）
3. 返回 **“凭证”** 并点击 **“创建凭证”>“OAuth 客户端 ID”**
4. 如果提示，请选择 **“桌面应用”** 作为应用类型
5. 输入 OAuth 客户端名称（例如“Google 日历 MCP 客户端”）
6. 点击 **“创建”**
7. **重要**：立即复制 **客户端 ID** 和 **客户端密钥** - 您将需要这些信息用于您的 `.env` 文件
8. 点击 **“确定”** 关闭对话框
**注意**：客户端 ID 和客户端密钥是敏感凭证。请安全保管它们，永远不要将它们提交到版本控制中。
### 2. 配置环境变量
在根目录中创建 `.env` 文件：
```env
# Google 日历 API 凭证
GOOGLE_CLIENT_ID=您的客户端 ID
GOOGLE_CLIENT_SECRET=您的客户端密钥
GOOGLE_REDIRECT_URI=http://localhost:3000/oauth2callback
# OAuth2 Token（首次身份验证后生成）
GOOGLE_ACCESS_TOKEN=
GOOGLE_REFRESH_TOKEN=
# 可选：服务账户 JSON 文件路径（OAuth 的替代方案）
# GOOGLE_SERVICE_ACCOUNT_PATH=./service-account.json
# 日历 ID（默认为主要日历的“primary”）
CALENDAR_ID=primary
```
### 3. 安装依赖项和身份验证
```bash
npm install
```
然后进行身份验证：
如果使用 OAuth 2.0，您可以使用附带的身份验证助手：
```bash
npm run auth
```
这将：
1. **自动启动本地 HTTP 服务器** 以捕获 OAuth 重定向
2. **打开浏览器** 显示授权 URL（或显示您要复制的 URL）
3. 在您授权后，**自动捕获授权代码**
4. **自动交换代码为令牌**
5. **更新您的 `.env` 文件** 包含令牌
**注意**：确保 `http://localhost:3000/oauth2callback` 已添加到 Google Cloud 控制台中您的 OAuth 客户端的授权重定向 URI 中。
**替代方案：手动身份验证**
您还可以使用 Google OAuth 2.0 游乐场：
1. 访问 [Google OAuth 2.0 游乐场](https://developers.google.com/oauthplayground/)
2. 选择“日历 API v3”作用域
3. 授权并获取令牌
4. 将令牌添加到您的 `.env` 文件中
### 4. 构建项目
```bash
npm run build
```
## 用法
### 运行服务器
```bash
npm start
```
或使用自动重新加载进行开发：
```bash
npm run dev
```
服务器在标准输入/输出上运行，并通过 MCP 协议进行通信。
### 可用工具
#### `list_events`
列出 Google 日历中的事件。
**参数：**
- `timeMin` （可选）：事件结束时间的下限（ISO 8601 格式）
- `timeMax` （可选）：事件开始时间上限（ISO 8601 格式）
- `maxResults` （可选）：最大事件数（默认：10）
- `calendarId` （可选）：日历 ID（默认：“primary”）
**示例：**
```json
{
"timeMin": "2024-01-01T00:00:00Z",
"timeMax": "2024-12-31T23:59:59Z",
"maxResults": 20
}
```
#### `create_event`
在 Google 日历中创建新事件。
**参数：**
- `summary` （必填）：事件标题
- `startDateTime` （必填）：开始日期/时间（ISO 8601 格式）
- `endDateTime` （必填）：结束日期/时间（ISO 8601 格式）
- `description` （可选）：事件描述
- `location` （可选）：事件地点
- `timeZone` （可选）：时区（默认：“UTC”）
- `attendees` （可选）：与会者电子邮件地址数组
- `calendarId` （可选）：日历 ID（默认：“primary”）
**示例：**
```json
{
"summary": "团队会议",
"description": "每周团队同步",
"startDateTime": "2024-01-15T10:00:00Z",
"endDateTime": "2024-01-15T11:00:00Z",
"timeZone": "America/New_York",
"location": "会议室 A",
"attendees": ["colleague@example.com"]
}
```
#### `update_event`
更新现有事件。
**参数：**
- `eventId` （必填）：要更新的事件 ID
- 所有其他参数均为可选（与 `create_event` 相同）
#### `delete_event`
从日历中删除事件。
**参数：**
- `eventId` （必填）：要删除的事件 ID
- `calendarId` （可选）：日历 ID（默认：“primary”）
#### `get_event`
获取特定事件的详细信息。
**参数：**
- `eventId` （必填）：要检索的事件 ID
- `calendarId` （可选）：日历 ID（默认：“primary”）
## MCP 客户端配置
添加到您的 MCP 客户端配置（Cursor，Claude Desktop）：
```json
{
"mcpServers": {
"google-calendar": {
"command": "node",
"args": ["/absolute/path/to/dist/index.js"],
"env": {
"GOOGLE_CLIENT_ID": "您的客户端 ID",
"GOOGLE_CLIENT_SECRET": "您的客户端密钥",
"GOOGLE_ACCESS_TOKEN": "您的访问令牌",
"GOOGLE_REFRESH_TOKEN": "您的刷新令牌"
}
}
}
}
```
有关 Docker 设置，请参阅 [DOCKER.md](DOCKER.md)
## 故障排除
### “Google 日历 API 在项目 X 中尚未使用过或已禁用”
此错误意味着 Google 日历 API 在您的 Google Cloud 项目中未启用。
**解决方案：**
1. 访问 [Google Cloud 控制台](https://console.cloud.google.com/)
2. 选择您的项目
3. 导航到 **“API 和服务”>“库”**
4. 搜索“Google 日历 API”并启用它
5. 等待几分钟，让更改传播
6. 重试您的请求
**直接链接到启用 API：**
将 `YOUR_PROJECT_ID` 替换为您的实际项目 ID：
```
https://console.cloud.google.com/apis/library/calendar-json.googleapis.com?project=YOUR_PROJECT_ID
```
### “缺少 Google OAuth 凭证”错误
- 检查 `.env` 文件是否存在且包含正确的值
- 验证 `GOOGLE_CLIENT_ID` 和 `GOOGLE_CLIENT_SECRET` 是否已设置
- 确保值周围没有额外的空格或引号
- 确保 `.env` 文件位于项目根目录中
### “无效凭证”错误
- 验证您的客户端 ID 和客户端密钥是否正确
- 检查您的项目中是否启用了 Google 日历 API
- 确保 OAuth 同意屏幕已配置
- 确保您正在使用正确的项目凭证
### “令牌过期”错误
- 重新运行 `npm run auth` 以获取新令牌
- 或使用 [Google OAuth 2.0 游乐场](https://developers.google.com/oauthplayground/) 刷新令牌
- 用新令牌更新您的 `.env` 文件
### 服务器无法启动
- 检查 Node.js 版本：`node --version` （需要 18+）
- 重建项目：`npm run build`
- 检查错误：`npm start`
- 验证所有依赖项是否已安装：`npm install`
### MCP 服务器连接问题
- 验证 `mcp.json` 中的路径是否正确并使用绝对路径
- 检查 `dist/index.js` 是否存在（如果丢失，请运行 `npm run build`）
- 确保您的 MCP 配置中已正确设置环境变量
- 在配置更改后重启您的 MCP 客户端（Cursor/Claude Desktop）
## 替代方案：服务账户
用于服务器到服务器身份验证：
1. 在 Google Cloud 控制台中创建服务账户
2. 下载 JSON 密钥文件
3. 与服务账户电子邮件地址共享您的日历
4. 在 `.env` 中设置 `GOOGLE_SERVICE_ACCOUNT_PATH`
## 开发
```bash
npm run dev # 开发模式，自动重新加载
```
## 许可证
MIT
