AI导哈

日历管理协议服务器

一个允许AI助手通过Model Context Protocol (MCP)与Google Calendar交互的服务，提供事件管理、可用性检查和日程安排功能。

  • by kxagent
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 tyleryouk/google-calendar-mcp

使用说明

Google 日历 MCP 服务器

一个模型上下文协议（MCP）服务器，允许Claude及其他MCP客户端与Google日历进行交互。该服务器使AI助手能够管理您的日历事件、检查可用性以及处理调度任务。

特点/特性

日历管理

  • 列出事件 （get-events)

    • 查看任意日历中的事件
    • 按时间范围筛选
    • 限制结果数量

  • 列出日历 (list-calendars)

    • 查看所有可用的日历
    • 访问日历ID和设置

  • 获取时区信息 (get-timezone-info)

    • 获取用户的时区信息

  • 获取当前日期 (get-current-date)

    • 获取用户时区的当前日期和时间
    • 适用于知识截止日期已过时的AI模型

活动运营

  • 创建活动 (create-event）

    • 安排新事件并支持全部功能
    • 添加参会者并设置提醒
    • 包含会议链接和附件
    • 设置可见性、透明度和颜色
    • 设置重复事件
    • 自动时区检测和冲突检查

  • 更新事件 (update-event）

    • 修改现有事件
    • 更改时间/日期并进行冲突检查
    • 添加/移除参会者
    • 更新任何活动详情
    • 控制通知设置

  • 删除事件 (delete-event)

    • 从日历中移除事件
    • 控制参会者的通知设置

可用性管理

  • 检查可用性 (check-availability)
    • 检查多个日历的空闲/忙碌状态
    • 时区意识
    • 支持检查其他用户的可用性

要求

  • Python >= 3.12
  • 已启用日历API的Google Cloud Console项目
  • OAuth 2.0 凭证

安装

1. 创建Google云项目

  1. 首选 Google Cloud 控制台
  2. 创建一个新项目或选择现有项目
  3. 启用Google日历API
  4. 创建OAuth 2.0凭据（桌面应用程序类型）
  5. 下载凭据并保存为 credentials.json 在 \mcp_server_google_calendar 文件夹中

2. 安装软件包

# Clone or download the project
cd mcp-google-calendar

# Install the package
pip install -e .

3. 认证设置

首次运行时，服务器将自动打开您的浏览器进行OAuth认证。您的凭据将被保存以便将来使用。

使用方法

这台服务器可以以两种模式运行：

STDIO 模式（适用于 Claude 代码）

配置Claude代码：

使用CLI添加服务器：

# Using the installed command (if installed globally)
claude mcp add --scope user google-calendar mcp-server-google-calendar

# Or using Python module with virtual environment (recommended)
claude mcp add --scope user google-calendar /home/kxdev/dev/mcp-servers/google-calendar-mcp/.venv/bin/python -- -m mcp_server_google_calendar

重启您的Claude代码会话 配置更改后。

SSE 模式（适用于Web应用程序和其他客户端）

使用SSE传输运行服务器：

# Using the installed command
mcp-server-google-calendar-sse

# Or using Python module
python -m mcp_server_google_calendar.server_sse

# With custom host/port
python -m mcp_server_google_calendar.server_sse --host 0.0.0.0 --port 8001

SSE服务器将在以下地址可用：

  • 服务器： http://localhost:8000
  • SSE 终端点： http://localhost:8000/sse

示例命令

以下是一些你可以问Claude的事情：

事件创建

  • “为明天下午2点创建一个名为‘团队会议’的事件”
  • “安排一个每周一上午10点的定期会议”
  • “与约翰安排在下周二下午进行视频通话”

活动管理

  • “把我的下午2点的会议改到下午4点”
  • “将简（jane@example.com）添加到明天的团队会议中”
  • “取消我和约翰的会议”
  • “更新今天团队午餐的地点”

日历查询

  • “我这周有什么会议？”
  • “我明天下午什么时候有空？”
  • “确认爱丽丝和鲍勃下周一下午3点是否都有空”
  • “列出我所有的重复事件”

日期/时间信息

  • “今天几号？”（对知识过时的模型很有用）
  • “今天星期几？”
  • “我当前所在的时区是什么？”

高级功能

时间冲突检测

服务器在创建或更新事件时会自动检查时间冲突，并会提醒您有关重叠事件的情况。

时区支持

  • 从您的Google日历设置中自动检测时区
  • 为事件手动指定时区
  • 正确处理时区转换

重复事件

全面支持使用iCalendar RRULE格式的重复事件：

  • 日常模式、周模式、月模式、年模式
  • 自定义重复规则
  • 例外日期和规则

参会者管理

  • 添加/移除参会者并进行电子邮件验证
  • 设置可选与必到参会者
  • 控制响应状态和通知
  • 支持额外宾客

故障排除

身份验证问题

  • 确保 credentials.json 位于项目根目录中
  • 检查Google Cloud Console中是否已配置OAuth同意屏幕
  • 验证日历API已启用
  • 删除 token.json 如有需要，强制重新进行身份验证

服务器连接问题

  • 验证 Python 版本（要求 >= 3.12）
  • 检查服务器是否已配置： claude mcp list
  • 配置更改后重启Claude代码会话
  • 对于SSE模式，请确保端口未被使用

事件创建问题

  • 在Google日历中确认日历权限
  • 检查与现有事件的时间冲突
  • 验证参会者的电子邮件地址是否有效
  • 确保时区格式正确

文件结构

mcp-google-calendar/
├── mcp_server_google_calendar/
│   ├── __init__.py
│   ├── __main__.py          # STDIO mode entry point
│   ├── __main_sse__.py      # SSE mode entry point
│   ├── credentials.json      # Google OAuth credentials (you provide)
│   ├── server.py            # STDIO server implementation
│   ├── server_sse.py        # SSE server implementation
│   ├── schemas.py           # Pydantic schemas
│   ├── auth/                # Authentication module
│   ├── tools/               # Tool definitions
│   └── utils/               # Utility functions
├── token.json              # Saved auth token (auto-generated)
├── pyproject.toml          # Project configuration
└── README.md

注释

  • 服务器为STDIO和SSE模式分别维护了具有相同功能的独立实现
  • 两种模式均支持自动时区检测和冲突检查
  • 所有时间应采用YYYY-MM-DDTHH:MM:SS格式或RFC3339标准指定
  • 日历ID“primary”指的是用户的默认日历
  • 事件更新保留未指定字段的现有数据
  • 服务器自动处理时区检测和转换

许可证

麻省理工学院许可证

相关 MCP