内容
# 谷歌日历 MCP 服务器
为Claude等AI助手提供谷歌日历集成的模型上下文协议（MCP）服务器。
## 功能
- **多日历支持**：同时列出多个日历的事件
- **事件管理**：创建、更新、删除和搜索日历事件
- **重复事件**：对重复事件的高级修改功能
- **空闲/忙碌查询**：跨日历检查可用性
- **智能调度**：对日期和时间的自然语言理解
- **智能导入**：从图片、PDF或网页链接添加日历事件
## 快速开始
### 前置条件
1. 启用了日历 API 的谷歌云项目
2. OAuth 2.0 凭证（桌面应用类型）
### 谷歌云设置
1. 访问 [谷歌云控制台](https://console.cloud.google.com)
2. 创建新项目或选择现有项目。
3. 为项目启用 [谷歌日历 API](https://console.cloud.google.com/apis/library/calendar-json.googleapis.com)。确保在启用 API 之前从顶部栏选择正确的项目。
4. 创建 OAuth 2.0 凭证：
- 访问凭证
- 点击“创建凭证”>“OAuth 客户端 ID”
- 选择“用户数据”作为应用访问的数据类型
- 添加应用名称和联系信息
- 添加以下作用域（可选）：
- `https://www.googleapis.com/auth/calendar.events` 和 `https://www.googleapis.com/auth/calendar`
- 选择“桌面应用”作为应用类型（重要！）
- 保存身份验证密钥，您需要在下一步中将其路径添加到 JSON 中
- 在 [受众屏幕](https://console.cloud.google.com/auth/audience) 中添加您的电子邮件地址作为测试用户
- 注意：可能需要几分钟才能添加测试用户。在测试用户传播之前，OAuth 同意不会允许您继续。
- 关于测试模式的说明：在测试模式下，身份验证令牌将在 1 周后过期，需要刷新（请参见下面的重新身份验证部分）。
### 安装
**选项 1：使用 npx（推荐）**
添加到您的 Claude Desktop 配置中：
**macOS**：`~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**：`%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"google-calendar": {
"command": "npx",
"args": ["@cocal/google-calendar-mcp"],
"env": {
"GOOGLE_OAUTH_CREDENTIALS": "/path/to/your/gcp-oauth.keys.json"
}
}
}
}
```
**⚠️ npx 用户的重要注意事项**：使用 npx 时，您 **必须** 使用 `GOOGLE_OAUTH_CREDENTIALS` 环境变量指定凭证文件路径。
**选项 2：本地安装**
```bash
git clone https://github.com/nspady/google-calendar-mcp.git
cd google-calendar-mcp
npm install
npm run build
```
然后使用本地路径或通过 `GOOGLE_OAUTH_CREDENTIALS` 环境变量指定路径，将其添加到 Claude Desktop 配置中。
**选项 3：Docker 安装**
```bash
git clone https://github.com/nspady/google-calendar-mcp.git
cd google-calendar-mcp
cp /path/to/your/gcp-oauth.keys.json .
docker compose up
```
参见 [Docker 部署指南](docs/docker.md)，了解详细的配置选项，包括 HTTP 传输模式。
### 首次运行
1. 启动 Claude Desktop
2. 服务器将在首次使用时提示身份验证
3. 在浏览器中完成 OAuth 流程
4. 您已准备好使用日历功能！
### 重新身份验证
如果您处于测试模式（默认），令牌将在 7 天后过期。如果您使用的是 Claude Desktop 等客户端，它应该会打开一个浏览器窗口以自动重新身份验证。但是，如果您看到身份验证错误，也可以通过以下步骤解决：
**对于 npx 用户：**
```bash
export GOOGLE_OAUTH_CREDENTIALS="/path/to/your/gcp-oauth.keys.json"
npx @cocal/google-calendar-mcp auth
```
**对于本地安装：**
```bash
npm run auth
```
**避免每周重新身份验证**，请将您的应用发布到生产模式（无需验证）：
1. 访问谷歌云控制台 → “API 和服务” → “OAuth 同意屏幕”
2. 点击“发布应用”并确认
3. 您的令牌将不再在 7 天后过期，但谷歌在连接应用时将显示更具威胁性的警告，表明应用未经验证。
参见 [身份验证指南](docs/authentication.md#moving-to-production-mode-recommended)，了解详细信息。
## 示例用法
除了日历集成的常规功能外，您还可以执行动态的多步骤流程，例如：
1. **跨日历可用性**：
```
请查看我的个人日历和工作日历，为下周找到一个合适的时间与某人在伦敦会面 1 小时。
```
2. 从截图、图片和其他数据源添加事件：
```
根据附件的截图，将此事件添加到我的日历中。
```
支持的图片格式：PNG、JPEG、GIF
图片可以包含事件详情，如日期、时间、地点和描述
3. 日历分析：
```
我本周有哪些不属于常规日程的即将到来的事件？
```
4. 检查出勤率：
```
明天哪些事件的与会者尚未接受邀请？
```
5. 自动协调事件：
```
这里有一些有人提供的可用时间。{可用时间}
查看提供的时间并告诉我哪些时间在我的日历上是空闲的。
```
## 可用工具
| 工具 | 描述 |
|------|-------------|
| `list-calendars` | 列出所有可用的日历 |
| `list-events` | 列出具有日期筛选的事件 |
| `search-events` | 按文本查询搜索事件 |
| `create-event` | 创建新的日历事件 |
| `update-event` | 更新现有事件 |
| `delete-event` | 删除事件 |
| `get-freebusy` | 检查跨日历的可用性，包括外部日历 |
| `list-colors` | 列出可用的事件颜色 |
## 文档
- [身份验证设置](docs/authentication.md) - 详细的谷歌云设置
- [高级用法](docs/advanced-usage.md) - 多账户、批量操作
- [部署指南](docs/deployment.md) - HTTP 传输、远程访问
- [Docker 指南](docs/docker.md) - Docker 部署，支持 stdio 和 HTTP 模式
- [OAuth 验证](docs/oauth-verification.md) - 从测试模式迁移到生产模式
- [架构](docs/architecture.md) - 技术架构概述
- [开发](docs/development.md) - 贡献和测试
- [测试](docs/testing.md) - 单元测试和集成测试指南
## 配置
**环境变量：**
- `GOOGLE_OAUTH_CREDENTIALS` - OAuth 凭证文件的路径
- `GOOGLE_CALENDAR_MCP_TOKEN_PATH` - 自定义令牌存储位置（可选）
**Claude Desktop 配置位置：**
- macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows：`%APPDATA%\Claude\claude_desktop_config.json`
## 安全
- OAuth 令牌安全存储在您的系统配置目录中
- 凭证永远不会离开您的本地机器
- 所有日历操作都需要明确的用户同意
### 故障排除
1. **OAuth 凭证文件未找到：**
- 对于 npx 用户：您 **必须** 使用 `GOOGLE_OAUTH_CREDENTIALS` 指定凭证文件路径
- 验证文件路径是否绝对且可访问
2. **身份验证错误：**
- 确保您的凭证文件包含 **桌面应用** 类型的凭证
- 验证您的用户电子邮件是否已作为 **测试用户** 添加到谷歌云 OAuth 同意屏幕
- 尝试删除保存的令牌并重新身份验证
- 检查是否没有其他进程阻止端口 3000-3004
3. **构建错误：**
- 再次运行 `npm install && npm run build`
- 检查 Node.js 版本（使用 LTS）
- 删除 `build/` 目录并运行 `npm run build`
4. **浏览器身份验证期间出现“出了问题”的屏幕**
- 按以下步骤执行手动身份验证
- 使用基于 Chromium 的浏览器打开身份验证 URL。某些非 Chromium 浏览器可能不支持测试应用身份验证。
### 手动身份验证
用于重新身份验证或故障排除：
```bash
# 对于 npx 安装
export GOOGLE_OAUTH_CREDENTIALS="/path/to/your/credentials.json"
npx @cocal/google-calendar-mcp auth
# 对于本地安装
npm run auth
```
## 许可证
MIT
## 支持
- [GitHub 问题](https://github.com/nspady/google-calendar-mcp/issues)
- [文档](docs/)
