使用说明

Google 日历 MCP 服务器

这是用于通过MCP（模型上下文协议）将Google日历连接到AI助手的服务器。它能够实现会议的自动检测、智能过滤以及高效的日程管理。

概要

通过使用该MCP服务器，Claude等AI助手能够安全地访问Google Calendar的数据，获取今天的会议信息或分析日程安排。特别是，它具有自动识别实际会议（计划有两名以上参与者）并过滤掉相关性较低的活动的功能。

主要功能

📅 日历 智能会议检测自动识别有两名以上参会者的实际会议
🎯（目标） 智能过滤自动排除预定缺席者、全天活动和非会议项目
🔐 安全认证使用PKCE的OAuth 2.0安全认证
⏰（时钟图标，通常表示时间或提醒） 时区对应完全的时区对应事件处理
🔄 旋转箭头（表示循环、重复或刷新等动作） 自动令牌更新过期访问令牌的自动更新
🎛️ 翻译为中文是“控制面板”或“仪表盘”。这个符号通常用来表示电子设备的控制面板或仪表界面。 可定制的过滤器关键词排除及参会者条件定制
机器人🤖 AI整合与Claude、ChatGPT等AI助手的简易集成

使用场景

此MCP服务器可用于以下场景：

AI助手辅助会议准备只需问“告诉我今天的会议”，AI就能获取相关会议信息
会议记录自动生成基于会议信息，AI准备会议纪要模板
进度分析AI分析会议趋势和时间分配
生成提醒AI在重要会议前提醒准备事项

前提条件

Node.js 18及以上版本
已启用Calendar API的Google Cloud Console项目
Google OAuth 2.0 认证信息（客户端ID和客户端密钥）

安装

1. 克隆仓库

git clone https://github.com/ham0215/google-calendar-mcp.git
cd google-calendar-mcp

2. 安装依赖项

npm install

3. 设置环境变量

cp .env.example .env

4. `.env`文件编辑

# 必須: Google OAuth認証情報
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret

# オプション: ポート変更（デフォルト: 3000）
# ポート3000が使用中の場合は、以下のように変更できます
# GOOGLE_REDIRECT_URI=http://localhost:3901/oauth/callback

# オプション: カスタマイズ設定
DEFAULT_TIMEZONE=Asia/Tokyo        # デフォルトのタイムゾーン
MIN_ATTENDEES=2                   # 会議と判定する最小参加者数
EXCLUDE_KEYWORDS=vacation,holiday,pto,ooo  # 除外するキーワード

注意： .env除了文件，也可以直接在Claude Desktop的设置文件中指定环境变量（详情请参见“与Claude Desktop的集成”部分）。

Google Cloud Console的设置

1. 创建项目

Google Cloud 控制台进行访问，创建新项目或选择现有项目

2. 启用Google日历API

选择“API和服务”→“启用API和服务”
搜索“Google Calendar API”
点击“启用”

3. 创建OAuth 2.0认证信息

选择“API和服务”→“凭证”
点击“创建认证信息”→“OAuth 客户端ID”
在应用程序类型中选择“Web应用程序”
在已批准的重定向URI中添加以下内容：
```
http://localhost:3000/oauth/callback
```
保存客户端ID和客户端密钥

使用方法

服务器构建

npm run build

服务器启动

在开发环境中的启动：

npm run dev

在生产环境启动：

npm run start

认证流程

此MCP服务器使用Google OAuth 2.0认证。首次启动时会自动开始认证流程。

首次启动时的自动认证

服务器启动时，若没有保存的令牌，则会自动启动认证流程
控制台上会显示认证URL
本地HTTP服务器（默认：端口3000）已启动并等待回调

认证步骤

npm run auth

执行后：

认证URL显示在控制台
在浏览器中打开URL并使用Google帐户登录
允许访问日历
自动获得代币~/.google-calendar-mcp/tokens.json并保存

代币的自动管理

访问令牌的有效期（通常为1小时）结束后会自动更新
使用刷新令牌自动获取新的访问令牌
仅当超过6个月时才需重新认证

与Claude Desktop的整合

在Claude Desktop上的使用

代币是~/.google-calendar-mcp/tokens.json被保存在
一旦认证，Claude Desktop启动时将自动处于已认证状态
在调用MCP工具时，令牌会自动使用

在使用Claude Desktop应用程序时，可通过以下两种方法进行设置：

方法1：使用.env文件（推荐）

项目路线.env创建文件并设置环境变量：

# .env ファイル
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_REDIRECT_URI=http://localhost:3000/oauth/callback  # ポート変更時
DEFAULT_TIMEZONE=Asia/Tokyo

claude_desktop_config.json仅指定路径：

{
  "mcpServers": {
    "google-calendar": {
      "command": "node",
      "args": ["/absolute/path/to/google-calendar-mcp/dist/index.js"]
    }
  }
}

方法2：在设置文件中直接指定

.env不使用文件claude_desktop_config.json直接记述于：

{
  "mcpServers": {
    "google-calendar": {
      "command": "node",
      "args": ["/absolute/path/to/google-calendar-mcp/dist/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret",
        "DEFAULT_TIMEZONE": "Asia/Tokyo"
      }
    }
  }
}

优势对比：

**方法1（.env）**在一处管理认证信息，使用与开发时相同的设置，且不通过Git管理
**方法2（直接指定）**将设置集中在一个文件中，便于在多个环境中使用不同的设置

设置文件的位置：

Mac： ~/Library/Application Support/Claude/claude_desktop_config.json
Windows： %APPDATA%\Claude\claude_desktop_config.json

可用工具

获取今天的会议

我们将通过智能筛选获取今天的会议信息。

参数：

timezone (字符串, 可选): 时区（默认：“UTC”，日本的情况：“Asia/Tokyo”）
includeDeclined （布尔值，选项）：是否包含预定缺席的会议（默认：false）
minAttendees （数值，可选）：最少参与者人数（默认：2）
excludeKeywords (字符串数组，可选): 从标题/说明中排除的关键词

使用示例（Claude内部）：

今日の会議を教えて
タイムゾーンをAsia/Tokyoで今日の予定を確認して
2人以上参加する会議だけを表示して

获取会议

通过智能筛选获取指定日期的会议。

参数：

date (字符串，必填)：日期（YYYY-MM-DD格式，例如：“2025-10-15”）
timezone (字符串, 可选): 时区（默认: "UTC"，日本的情况: "Asia/Tokyo"）
includeDeclined （布尔值，选项）：是否包含预计缺席的会议（默认：false）
minAttendees （数值，可选）：最少参与者数（默认：2）
excludeKeywords (字符串数组，可选): 要从标题/说明中排除的关键词

使用示例（Claude内部）：

2025年10月20日の会議を教えて
来週月曜日の予定を確認して
明日の会議で3人以上参加する予定を表示して

响应示例：

{
  "meetings": [
    {
      "id": "event-id",
      "title": "チーム定例会議",
      "startTime": "2024-01-20T10:00:00+09:00",
      "endTime": "2024-01-20T10:30:00+09:00",
      "duration": 30,
      "attendees": [
        {
          "email": "user@example.com",
          "name": "山田太郎",
          "responseStatus": "accepted",
          "isOrganizer": true
        },
        {
          "email": "colleague@example.com",
          "name": "鈴木花子",
          "responseStatus": "accepted",
          "isOrganizer": false
        }
      ],
      "location": "会議室A",
      "meetingLink": "https://meet.google.com/abc-defg-hij",
      "description": "週次進捗確認",
      "isAccepted": true,
      "isOrganizer": true
    }
  ],
  "timezone": "Asia/Tokyo",
  "date": "2024-01-20"
}

设定

环境变量

变量名	说明	默认值
`GOOGLE_CLIENT_ID`	Google OAuth 客户端ID	必填
`GOOGLE_CLIENT_SECRET`	Google OAuth 客户端密钥	必填
`GOOGLE_REDIRECT_URI`	OAuth 重定向URI	`http://localhost:3000/oauth/callback`
`DEFAULT_TIMEZONE`	默认时区	`UTC`
`DEFAULT_CALENDAR_ID`	默认的日历ID	`primary`
`MIN_ATTENDEES`	召开会议及做出决议所需的最少参会人数	`2`
`EXCLUDE_KEYWORDS`	要排除的关键词（逗号分隔）	参见下文
`REQUIRE_ACCEPTED`	仅显示已承诺的会议	`true`
`EXCLUDE_DECLINED`	排除预定缺席的会议	`true`
`EXCLUDE_ALL_DAY`	排除全天活动	`true`
`TOKEN_DIR`	令牌保存目录	`~/.google-calendar-mcp`

默认排除关键词

包含以下关键词的活动将被自动排除（不区分大小写）：

不在办公室，OOO（不在）
假期、假日、带薪休假（休假相关）
被阻止，忙碌中，保持（预定保持）
暂定，专注时间
午餐，休息时间

开发

可用脚本

# 開発環境（ホットリロード付き）
npm run dev

# TypeScriptのビルド
npm run build

# ビルドディレクトリのクリーンとリビルド
npm run rebuild

# 本番環境での起動
npm run start

# 開発環境での起動（tsx使用）
npm run start:dev

# 型チェック
npm run typecheck

# リンターの実行
npm run lint

# リンターの実行（自動修正付き）
npm run lint:fix

# コードフォーマット
npm run format

# コードフォーマットチェック
npm run format:check

# すべてのチェックを実行（型チェック + リンター）
npm run check

# テストの実行（watchモード）
npm test

# テストの実行（CI用、一度だけ実行）
npm run test:run

# テストのUI表示
npm run test:ui

# テストカバレッジ
npm run test:coverage

# ビルドディレクトリのクリーン
npm run clean

# 認証のセットアップ
npm run auth

项目构成

google-calendar-mcp/
├── src/
│   ├── index.ts           # MCPサーバーのエントリーポイント
│   ├── auth/              # OAuth認証とトークン管理
│   │   ├── oauth.ts       # OAuth認証フロー実装
│   │   └── token-manager.ts # トークンの保存と更新
│   ├── calendar/          # Calendar API統合
│   │   ├── client.ts      # Google Calendar APIクライアント
│   │   └── filters.ts     # イベントフィルタリングロジック
│   ├── config/            # 設定管理
│   │   └── settings.ts    # 環境設定
│   ├── tools/             # MCPツール実装
│   │   └── get-meetings.ts # getTodayMeetings/getMeetingsツール
│   └── types/             # TypeScript型定義
│       └── index.ts       # 共通型定義
├── dist/                  # コンパイル済みJavaScript
├── docs/                  # ドキュメント
│   └── development-tasks.md # 開発タスクリスト
├── tests/                 # テストファイル
├── .env.example          # 環境変数テンプレート
├── tsconfig.json         # TypeScript設定
└── package.json          # プロジェクト依存関係

故障排除

处理认证错误

如认证出现问题时：

删除令牌文件： rm ~/.google-calendar-mcp/tokens.json
重启服务器并重新认证
在Google Cloud Console中确认OAuth客户端是否设置正确

代币的有效期

服务器会自动更新过期的令牌，但在以下情况下需要重新认证：

已过期超过6个月的代币
如果Google Cloud项目已被禁用

API限制

Google Calendar API有使用限制。本服务器已实施以下对策：

基于指数退避的自动重试
检测速率限制并等待
超出配额时的适当错误处理

常见问题

问：未显示“今日会议”

A: 请确认时区设置是否正确。如果是日本的话DEFAULT_TIMEZONE=Asia/Tokyo进行设定。

问：特定活动被排除在外

A：请确认排除关键词。EXCLUDE_KEYWORDS可通过环境变量进行自定义。

问：无法访问认证URL

A：默认使用端口3000。如果已被其他应用程序使用，请通过环境变量GOOGLE_REDIRECT_URI请指定其他端口（例如：3901）。

安全

OAuth令牌将本地保存在用户的主目录中
通过PKCE（Proof Key for Code Exchange）实现的安全增强（src/auth/oauth.ts:46-127）
实现防止CSRF攻击的state验证
在本地HTTP服务器上自动处理回调
通过令牌自动更新功能将重新认证次数降至最少（src/auth/token-manager.ts:96-127）
不要将认证信息提交到版本管理中

在Findy上的应用

该MCP服务器被用于Findy的以下业务：

会议记录自动生成根据会议信息在Notion中创建会议记录模板
提高会议准备效率AI自动收集相关资料和过往会议记录
进度分析会议时间分配及参会率分析

贡献

我们欢迎您的贡献！请按以下步骤操作：

克隆仓库
创建特性分支
实施变更
（根据需要）增加测试
发送拉取请求

许可证

MIT许可证 - 详情见许可证查阅文件

支持

如有问题、疑问或建议，请在GitHub上创建Issue。