G2N MCP Google Calendar SSE Server

G2N MCP Google Calendar SSE 服务

🌎 此 README 提供多种语言版本：

• 🇺🇸 英语
• 🇧🇷 葡萄牙语

概述

G2N MCP Google Calendar SSE 服务是一种模型上下文协议（MCP）服务实现，通过服务器发送事件（SSE）提供 Google Calendar 集成。此服务将 Google Calendar 功能作为工具提供，供 Cursor、Claude 和 n8n 等 AI 模型和应用与 Google Calendar 交互。

此服务采用最新版本的 MCP SDK 构建，可为兼容 MCP 的模型与 Google Calendar 服务提供稳健的集成。

功能

此服务提供以下用于管理 Google Calendar 的 MCP 工具：

• list-calendars：列出所有可用的日历
• get-calendar：获取特定日历的详细信息
• list-events：列出日历中的事件，并提供筛选选项
• get-event：获取特定事件的详细信息
• create-event：创建新的日历事件
• update-event：更新现有日历事件
• delete-event：删除日历事件
• list-colors：列出事件和日历的可用颜色

v1.1.0 新增内容

• 全面的日志记录系统，支持配置日志级别
• 请求/响应日志中间件，便于监控
• SSE 心跳机制，确保连接稳定
• 增强错误处理和调试能力
• 改进 Docker 配置，正确设置数据目录权限
• 增强 OAuth 流程，改进令牌管理
• 重构代码，提升可维护性

v1.0.1 新增内容

• 首个稳定版本
• 可用于生产环境，支持 Docker 和 Docker Swarm
• 增强环境变量配置
• 改进不同部署场景下的连接 URL
• 完善 n8n 集成文档
• Traefik 配置指南
• 多平台 Docker 镜像（amd64、arm64、arm/v7）

入门

前提条件

• 已安装 Docker 和 Docker Compose
• 已启用 Calendar API 的 Google Cloud 项目
• OAuth 2.0 客户端 ID 和客户端密钥

环境变量

此服务使用以下环境变量：

PORT=3001                                # Server port (default: 3001)
PUBLIC_URL=https://your-domain.com       # Public URL for OAuth callbacks
GOOGLE_CLIENT_ID=${GOOGLE_CLIENT_ID}     # Google OAuth Client ID
GOOGLE_CLIENT_SECRET=${GOOGLE_CLIENT_SECRET} # Google OAuth Client Secret
OAUTH_REDIRECT_PATH=/oauth/callback      # OAuth callback path (default: /oauth/callback)

重要说明：

• 使用 Traefik 时，请确保将其配置为指向 PORT 环境变量指定的端口
• 这对于成功接收 Google 刷新令牌至关重要
• PUBLIC_URL 必须可通过互联网访问，OAuth 回调才能正常工作

身份验证流程

1. 使用 Docker 启动服务，或直接启动
2. 在浏览器中访问 /auth 端点
3. 使用你的 Google 账号向应用授予权限
4. 授权后，服务将存储刷新令牌，以便持续访问
5. 服务会在需要时自动刷新令牌

如需撤销访问权限，请使用 /revoke 端点：

curl -X POST https://your-domain.com/revoke

在兼容 MCP 的应用中使用

连接 URL

根据部署场景，使用相应的 URL 格式：

1. Docker Swarm / n8n 内部访问：

   http://[stack-service-name]:3001/sse
   

   示例：如果你的服务在堆栈中名为 g2n-mcp-gcal-sse，请使用：

   http://g2n-mcp-gcal-sse:3001/sse
   

2. 外部访问（Cursor、Claude 等）：

   https://your-domain.com/sse
   

3. 本地开发：

   http://localhost:3001/sse
   

Cursor AI

你可以通过在设置中配置 MCP 连接，将此服务与 Cursor AI 配合使用：

1. 打开 Cursor 设置
2. 使用你的公共域名配置 MCP 服务 URL：

   https://your-domain.com/sse
   

3. 通过 AI 命令开始使用 Google Calendar 功能

Claude Desktop

对于 Claude Desktop：

1. 前往 Settings > MCP
2. 使用你的公共 URL 添加新的 MCP 连接：

   https://your-domain.com/sse
   

3. 在对话中使用 Google Calendar 功能

n8n

1. 在 n8n 中添加新的 MCP 节点
2. 使用内部服务 URL 配置 MCP 节点：

   http://[stack-service-name]:3001/sse
   

3. 在工作流中使用已提供的日历工具

许可证

此项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

关于 G2NTech

本项目由 G2NTech 的 Gabriel Augusto 开发和维护。

支持本项目 💜

如果您觉得本项目有用，可以考虑通过 PIX 支持我们：

• PIX 密钥： [email protected]