Google Calendar

🚀 谷歌カレンダー MCP サーバー

TypeScript で構築された Model Context Protocol (MCP) サーバーで、Google カレンダー機能を統合しています。

✨ 主な機能

• シームレスな Google カレンダー統合：OAuth 2.0 認証をサポート
• トークンの永続的な保存：自動認証を実現
• カレンダー管理：カレンダーとそのイベントを一覧表示し、操作可能
• イベントの全ライフサイクル操作：カレンダーイベントの作成、読み取り、更新、削除が可能
• 日付範囲でのイベント取得：指定された期間内のカレンダーイベントを照会
• リアルタイム更新のプッシュ：Server-Sent Events (SSE) 伝送プロトコルをサポート
• 簡単な統合：Claude や他の MCP 互換の AI アシスタントと互換性がある

📦 インストール

npm install -g mcp-google-calendar

または、直接実行する場合は：

npx -y mcp-google-calendar

前提条件

1. Node.js（v16 以上）
2. Google Cloud Platform アカウント
3. Google カレンダー API が有効になっていること
4. OAuth 2.0 の認証情報が設定されていること

設定ガイド

1. Google Cloud Platform の設定

1. Google Cloud Console にアクセス
2. 新しいプロジェクトを作成するか、既存のプロジェクトを選択
3. Google カレンダー API を有効にする：
   • "APIs & Services" > "Library" に移動
   • "Google Calendar API" を検索
   • "Enable" をクリック
4. OAuth コンセント画面を設定する：
   • "APIs & Services" > "OAuth consent screen" にアクセス
   • "External" ユーザータイプを選択（Google Workspace の場合は "Internal"）
   • 必要な情報を入力：
     • アプリ名：mcp-calendar
     • ユーザーサポートメール：(あなたのメールアドレス)
     • 開発者連絡先：(あなたのメールアドレス)
   • 権限スコープを追加する：
     • "Add or Remove Scopes" をクリック
     • "https://www.googleapis.com/auth/calendar.events" を見つけて選択
     • あなたのメールアドレスをテストユーザーとして追加
   • 設定手順を完了する
5. OAuth 認証情報を作成する：
   • "Credentials" セクションに移動
   • "Create Credentials" > "OAuth Client ID" をクリック
   • アプリケーションタイプを "Desktop app" として選択
   • 名前を付ける（例：MCP Calendar Desktop Client）
   • JSON ファイルをダウンロードし、プロジェクトディレクトリ内の credentials.json として保存

2. 環境設定

プロジェクトのルートディレクトリに .env ファイルを作成します。

# サーバー設定
PORT=3420

# Google カレンダー API 設定
CREDENTIALS_PATH=./credentials.json

💻 使用例

サーバーの起動

標準の WebSocket で実行する場合：

npx -y mcp-google-calendar

Server-Sent Events (SSE) で実行する場合：

npx -y mcp-google-calendar --sse

Claude Desktop との統合

claude_desktop_config.json に以下の設定を追加します。

{
   "mcpServers": {
      "mcp-google-calendar": {
         "command": "npx",
         "args": ["-y", "mcp-google-calendar"]
      }
   }
}

基本的な使用法

認証と承認

1. 承認コードの取得：OAuth 2.0 を通じてアクセストークンを取得するための承認コードを取得します。
2. トークンの更新：トークンの自動更新メカニズムを実装し、長期間のアクセスを保証します。

カレンダー管理

カレンダーの作成

const calendar = await createCalendar({
  summary: 'My New Calendar',
  description: 'This is a new calendar created via API'
});

カレンダーの読み取り

指定されたカレンダーの詳細情報（名前、説明など）を取得します。

カレンダーの更新

既存のカレンダーの属性（名前や説明など）を変更します。

カレンダーの削除

不要になったカレンダーを削除します。

イベント管理

イベントの作成

const event = await createEvent({
  calendarId: 'primary',
  summary: 'Meeting with Team',
  description: 'Discuss Q4 project plan',
  start: {
    timeZone: 'Asia/Shanghai',
    dateTime: '2023-10-05T09:00:00'
  },
  end: {
    timeZone: 'Asia/Shanghai',
    dateTime: '2023-10-05T10:30:00'
  }
});

イベントの一覧表示

const events = await listEvents({
  calendarId: 'primary',
  timeMin: '2023-10-01T00:00:00',
  timeMax: '2023-10-31T23:59:59'
});

イベントの更新

const updatedEvent = await updateEvent({
  calendarId: 'primary',
  eventId: 'event_id_123',
  summary: 'Updated Meeting'
});

イベントの削除

await deleteEvent({
  calendarId: 'primary',
  eventId: 'event_id_123'
});

リアルタイム通知

SSE を通じてイベントのリアルタイム更新通知を実現し、特定のカレンダーのすべてのイベント変更を購読します。

🔧 技術詳細

プロジェクト構造

src/
├── index.ts          # エントリーファイル
├── calendar.ts       # カレンダー管理モジュール
├── event.ts          # イベント管理モジュール
└── auth.ts           # 認証と承認モジュール

開発の始め方

1. 依存関係のインストール：

npm install @types/googleapis google-auth-library

2. プロジェクトの初期化：

npx tsinit

3. コードの記述と実行：

npm run dev

📄 セキュリティに関する注意事項

⚠️ 重要提示

1. 認証情報の管理：credentials.json ファイルの安全性を確保し、機密情報の漏洩を防ぎます。
2. 権限管理：API 呼び出しの権限範囲を厳密に制限し、不正な操作を防止します。
3. ログ監視：API のリクエストとレスポンスをリアルタイムで監視し、異常な動作を早期に検出します。
4. エラー処理：様々な API エラーコードと例外状況に対応する、堅牢なエラー処理メカニズムを設計します。