Google Calendar MCP 服务器 - 安装和使用指南

📘 概述

Model Context Protocol (MCP) 服务器，提供对 Google Calendar API 的访问，并支持异步操作。通过标准接口，实现高效的日历管理。

🚀 主要特性

• 无缝连接 Google Calendar API
• 支持异步操作，实现最佳性能
• OAuth 2.0 身份验证系统，支持自动续订令牌
• 全面的错误处理和日志记录
• 简化的 MCP 接口，可与 Claude 和其他 AI 集成

🔑 API 工具

工具	描述
list	获取日历中的事件列表（过去 2 年到未来 1 年）
create-event	在日历中创建新事件
delete-duplicates	删除重复的事件
delete-event	删除指定的事件

🛠️ 安装

前提条件

• Python 3.9 或更高版本
• 互联网连接
• 启用了 Google Calendar API 的 Google Cloud Console 项目

安装步骤

1. 克隆项目

   git clone https://github.com/yourusername/GCalendar.git
   cd GCalendar
   

2. 创建虚拟环境（推荐）

   python -m venv gcalendar_venv
   
   # 对于 Windows
   gcalendar_venv\Scripts\activate
   
   # 对于 macOS/Linux
   source gcalendar_venv/bin/activate
   

3. 安装必要的软件包

   pip install -r requirements.txt
   

4. 准备必要的文件夹

   mkdir -p credentials logs
   

身份验证设置

1. 创建 Google Cloud Console 项目

   • 访问 Google Cloud Console
   • 创建新项目
   • 启用 Google Calendar API
   • 创建 OAuth 2.0 Client ID
   • 将 credentials.json 下载到 credentials/ 文件夹

2. 创建令牌

   python src/create_token.py
   

   • 按照浏览器中的步骤授予访问权限
   • 令牌将保存到 credentials/ 文件夹中，命名为 token.json

⚙️ 技术配置

MCP 服务器配置

添加到 claude_desktop_config.json 文件中：

{
  "mcpServers": {
    "gcalendar": {
      "command": "YOUR_PYTHON_PATH",
      "args": [
        "YOUR_PATH/GCalendar/src/mcp_server.py"
      ]
    }
  }
}

替换占位符：

• YOUR_PYTHON_PATH: Python 解释器的路径（来自 venv 或 conda）
• YOUR_PATH: 克隆文件夹的完整路径

项目结构

GCalendar/
├── credentials/
│   ├── credentials.json   # 来自 Google Cloud Console
│   └── token.json        # 由 create_token.py 创建
├── logs/
│   └── calendar_service.log
├── src/
│   ├── calendar_service.py   # 核心日历操作
│   ├── create_token.py      # 令牌创建
│   ├── list_past_events.py  # 事件列表实用程序
│   ├── mcp_client.py        # MCP 客户端实现
│   ├── mcp_server.py        # 核心服务器实现
│   └── renew_token.py       # 令牌续订实用程序
├── requirements.txt
└── README.md

📋 使用

启动服务器

1. 手动启动服务器

   python src/mcp_server.py
   

2. 与 Claude Desktop 一起使用

   • 按照上述配置部分中的说明进行配置
   • Claude 将在需要时自动启动服务器

命令示例

1. 查看日历中的事件列表

   显示我的日历事件
   

2. 创建新事件

   创建一个名为“团队会议”的会议，日期为 2025 年 3 月 25 日，时间为 14:00 到 15:00
   

3. 删除重复的事件

   删除 2025 年 3 月 25 日重复的“团队会议”事件
   

🔍 故障排除

身份验证问题

1. 检查 credentials.json 和 token.json 文件是否位于 credentials/ 文件夹中
2. 删除 token.json 并使用 create_token.py 重新创建

时区问题

1. 检查是否已安装 timezone 库：

   pip install pytz tzdata
   

检查日志

1. 查看日志文件以获取有关错误的更多信息：

   cat logs/calendar_service.log
   

📚 依赖项

• google-auth-oauthlib==1.0.0
• google-auth-httplib2==0.1.0
• google-api-python-client==2.108.0
• aiohttp==3.8.5
• asyncio==3.4.3
• pytz==2023.3
• tzdata==2023.3

📄 许可证

本项目根据 MIT 许可证获得许可。 有关详细信息，请参阅 LICENSE 文件。 "# py-mcp-gcalendar"