MCP Google Calendar Plus

MCP谷歌工作区

谷歌工作区唯一一款全面的MCP服务器，使Claude、Cursor、Windsurf和其他人工智能系统能够完全管理谷歌日历、联系人和Gmail -跨所有三个服务进行读取、创建、更新、删除和组织！

使用模型上下文协议（MCP）为Claude Desktop和其他AI代理完成Google Workspace集成。此服务器通过OAuth2身份验证为日历、联系人和Gmail提供全面的管理功能。

为什么选择MCP服务器？

其他日历MCP服务器仅提供 只读的 访问。这就是 仅MCP服务器 这使Claude、Cursor和Windsurf等人工智能系统能够：

日历管理

• ✅ 创建 新日历事件
• ✅ 更新 现有事件（包括重复事件）
• ✅ 删除 事件
• ✅ 管理 多个日历
• ✅ 检查可用性 跨日历

联系人管理

• ✅ 列表 并搜索联系人
• ✅ 创建 提供完整详细信息的新联系人
• ✅ 更新 现有联系人
• ✅ 删除 联系人
• ✅ 管理 联系方式（电子邮件、电话、地址、组织）

Gmail管理（新增！）

• ✅ 搜索 并列出具有强大查询功能的电子邮件
• ✅ 阅读 带附件的完整电子邮件内容
• ✅ 发送 新电子邮件和回复
• ✅ 组织 带有标签和文件夹
• ✅ 更新 电子邮件状态（已读/未读、星号、重要）
• ✅ 创建 并管理草稿
• ✅ 批量操作 用于批量电子邮件管理

特性

日历功能

• 多日历支持：同时列出多个日历中的事件
• 事件管理：创建、更新（包括通知）、删除和搜索日历事件
• 重复发生的事件：重复事件的高级修改范围（单个实例、所有实例或仅未来实例）
• 日历管理：列出日历及其属性
• 忙/闲查询：检查日历上的可用性

联系人特征

• 联系人搜索：按姓名、电子邮件或其他条件搜索联系人
• 完整联系方式：管理姓名、电子邮件、电话号码、地址、组织和笔记
• 批量操作：列出支持分页的联系人
• 字段选择：选择要检索哪些联系人字段以获得优化响应

Gmail功能（新增！）

• 高级搜索：使用Gmail强大的搜索运营商
• 电子邮件管理：阅读、发送、回复、转发和删除电子邮件
• 标签组织：创建和管理标签/文件夹
• 草案管理：创建、更新和发送草稿
• 批量操作：一次更新多封电子邮件
• 线程支持：处理电子邮件对话
• 附件信息：查看附件详细信息（名称、大小、类型）

认证

• OAuth2身份验证：通过自动令牌刷新进行安全身份验证
• 统一权限：日历、联系人和Gmail访问的单一身份验证流程

安装

通过npx（推荐）

npx mcp-google

通过npm

npm install -g mcp-google

设置

1.创建Google OAuth凭据

1. 首选 谷歌云控制台
2. 创建新项目或选择现有项目
3. 启用这些API：

- 谷歌日历API - 谷歌人API

1. 配置OAuth同意屏幕：

- 转到“API和服务”>“OAuth同意屏幕” - 选择“外部”用户类型 - 填写必填字段（应用程序名称、支持电子邮件等） - 将您的电子邮件添加为测试用户（在测试模式下需要）

1. 创建OAuth 2.0凭据：

- 转到“API和服务”>“凭据” - 点击“创建凭据”>“OAuth客户端ID” - 选择 “桌面应用程序” 作为应用程序类型 - 命名您的OAuth客户端（例如，“MCP日历客户端”） - 下载凭据JSON文件

2.配置克劳德桌面

将此添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

选项A：直接环境变量（最简单-不需要JSON文件！）

{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": ["-y", "mcp-google"],
      "env": {
        "GOOGLE_CLIENT_ID": "YOUR_CLIENT_ID.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "YOUR_CLIENT_SECRET"
      }
    }
  }
}

选项B：使用下载的Google凭据文件

{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": ["-y", "mcp-google"],
      "env": {
        "GOOGLE_OAUTH_CREDENTIALS": "/path/to/downloaded/credentials.json"
      }
    }
  }
}

只需使用从Google Cloud Console下载的JSON文件的保存路径。

3.身份验证

1. 重新启动克劳德桌面
2. MCP服务器将打开一个浏览器窗口进行身份验证
3. 使用您的Google帐户登录并授予日历、联系人和Gmail权限
4. 代币将被安全地保存以备将来使用

注： 如果从以前的版本升级，您需要重新进行身份验证以授予新的Gmail权限。

环境变量

• GOOGLE_OAUTH_CREDENTIALS：OAuth凭据JSON文件的路径
• GOOGLE_CALENDAR_MCP_TOKEN_PATH：令牌存储的自定义路径（可选）
• NODE_ENV：设置为“生产”以供生产使用

可用工具

日历工具

列出日历

列出所有可访问的日历及其属性。

列出事件

使用筛选选项列出一个或多个日历中的事件。

创建事件

创建新的日历事件，支持：

• 单一或重复发生的事件
• 与会者和通知
• 自定义颜色
• 时区

更新事件

更新现有事件，包括：

• 修改重复事件的单个实例
• 更改事件详细信息
• 管理与会者

删除事件

从日历中删除事件。

搜索事件

使用文本查询跨日历搜索事件。

获得免费赠品

跨多个日历查询忙/闲信息。

列出颜色

列出可用的日历事件颜色。

联系工具

列出联系人

列出和搜索支持分页的联系人。

取得联系

获取特定联系人的详细信息。

创建联系人

通过以下方式创建新联系人：

• 姓名和昵称
• 多个电子邮件地址
• 电话号码
• 物理地址
• 组织和职位
• 笔记和传记

更新联系人

用特定领域的更新更新现有的联系信息。

删除联系人

从Google联系人中删除联系人。

Gmail工具（新增！）

列出电子邮件

使用强大的Gmail查询搜索和列出电子邮件。

获取电子邮件

阅读完整的电子邮件内容，包括正文和附件。

发送电子邮件

发送支持HTML的新电子邮件或回复。

更新电子邮件

修改电子邮件属性（标签、读取状态、星号、存档）。

删除电子邮件

将电子邮件移至垃圾箱或永久删除。

创建草稿

创建电子邮件草稿以供以后编辑。

更新草稿

编辑现有电子邮件草稿。

发送草稿

发送已保存的草稿。

列表标签

列出所有Gmail标签/文件夹。

创建标签

创建用于组织电子邮件的新标签。

更新标签

修改标签属性和颜色。

删除标签

从Gmail中删除标签。

批量更新电子邮件

对多封电子邮件执行批量操作。

示例用法

日历示例

检查可用性

What times am I free tomorrow between 9am and 5pm?

创建事件

Create a meeting called "Team Standup" tomorrow at 10am for 30 minutes

搜索活动

Find all events this week that mention "project review"

更新重复事件

Change all future instances of my weekly team meeting to 2pm

联系人示例

列出联系人

Show me all my contacts with email addresses

创建联系人

Create a contact for John Doe, email: john@example.com, phone: 555-1234

搜索联系人

Find contacts who work at Google

更新联系人

Update Jane Smith's phone number to 555-5678

Gmail示例

搜索电子邮件

Show me all unread emails from this week

发送电子邮件

Send an email to john@example.com with subject "Meeting Tomorrow" and body "Let's meet at 2pm"

整理收件箱

Mark all newsletters as read and archive them

管理标签

Create a label called "Important Projects" and apply it to all emails from my manager

批量操作

Move all emails older than 30 days to trash

故障排除

身份验证问题

• 确保重定向URI完全匹配： http://localhost:3000/oauth2callback
• 检查日历API和人员API是否已在Google云控制台中启用
• 验证OAuth凭据是否适用于“桌面应用程序”类型
• 如果仅从日历升级，请重新运行身份验证以授予联系人权限

令牌到期

• 令牌会自动刷新
• 如果问题仍然存在，请删除令牌文件并重新进行身份验证

权限错误

• 确保您已授予所有请求的日历、联系人和Gmail权限
• 检查Google帐户是否可以访问您尝试访问的资源
• 确保您的Google Cloud项目中启用了所有必需的API：

- 谷歌日历API - 谷歌人API - Gmail API

安全

• OAuth令牌以受限权限存储（0600）
• 客户端机密永远不应提交给版本控制
• 使用环境变量进行敏感配置

发展

# Install dependencies
npm install

# Build
npm run build

# Run locally
npm start

团队

建在原来的基础上 谷歌日历mcp nspady。

许可证

麻省理工学院

贡献

欢迎投稿！请在上打开问题或提交拉取请求 .

更新日志

v1.1.3

• 修复了时区验证，以支持ISO时间戳中的毫秒
• 现在与JavaScript兼容 Date.toISOString() 格式（例如。， 2024-01-01T00:00:00.000Z)
• 改进了日期时间验证正则表达式，以处理有毫秒和没有毫秒的两种格式

v1.1.2版本

• 通过清晰、信息丰富的登录页面改进了身份验证流程
• 用户现在可以在连接之前确切地看到Claude将拥有哪些权限
• 专业用户界面，明确标识为谷歌日历身份验证
• 添加了从不存储凭据的安全说明

v1.1.1

• 增强文档，突出独特的完整日历管理功能
• 添加了“为什么选择此MCP服务器？”一节，强调创建/更新/删除功能
• 更新了包描述和关键字，以提高可发现性

v1.1.0版本

• 简化设置：添加了对直接环境变量的支持（不需要JSON文件！）
• 用户现在可以使用 GOOGLE_CLIENT_ID 和 GOOGLE_CLIENT_SECRET 直接在Claude配置中
• 更新了README，提供了更清晰的桌面应用OAuth设置说明
• 删除了不必要的重定向URI配置步骤

v1.0.1

• 为网络错误添加了自动重试逻辑
• 改进了套接字挂起问题的错误处理
• 尽管存在连接错误，但创建事件时仍会进行静默恢复

v1.0.0

• 具有增强OAuth2身份验证的初始版本
• 全面的日历管理工具
• 多日历支持
• 忙/闲查询