Google Calendar MCP Server

🚀 Google Calendar MCP Server

Google Calendar MCP Serverは、Model Context Protocol (MCP) を使用したサーバーで、Google Calendarとの包括的な統合機能を提供します。このサーバーを使用することで、AIアシスタントやアプリケーションが標準化されたプロトコルを通じてGoogle Calendarとやり取りできます。

✨ 主な機能

• イベントの一覧表示：フィルタリングオプションを使用してGoogle Calendarからイベントを取得します。
• イベントの作成：完全にカスタマイズ可能な新しいカレンダーイベントを作成します。
• イベントの更新：既存のカレンダーイベントを修正します。
• イベントの削除：カレンダーからイベントを削除します。
• カレンダーの一覧表示：認証されたユーザーが利用可能なカレンダーを取得します。
• OAuth認証：Google Calendar APIへの安全なアクセスを提供します。

📦 インストール

前提条件

1. Google Cloudプロジェクト：Google Cloud Console でプロジェクトを作成します。
2. Google Calendar APIの有効化：プロジェクトでCalendar APIを有効にします。
3. サービスアカウント：サービスアカウントを作成し、JSONキーファイルをダウンロードします。

インストール手順

1. このリポジトリをクローンします。
2. 依存関係をインストールします。

   npm install
   

3. 環境ファイルをコピーして設定します。

   copy .env.example .env
   

4. .env ファイルを編集し、Googleサービスアカウントキーファイルのパスを設定します。

   GOOGLE_SERVICE_ACCOUNT_KEY_FILE=./path/to/your/service-account-key.json
   

ビルド

# TypeScriptコードをビルドします
npm run build

# ホットリロードを使用した開発モード
npm run dev

# 型チェック
npm run type-check

# ビルドアーティファクトをクリーンアップ
npm run clean

💻 使用例

サーバーの起動

# コンパイルされたサーバーを起動します
npm start

# または開発モードで実行
npm run dev

MCPクライアントとの統合

このサーバーをMCPクライアントの設定に追加します。

{
  "servers": {
    "google-calendar": {
      "type": "stdio",
      "command": "node",
      "args": ["./dist/index.js"]
    }
  }
}

VS CodeのMCP拡張機能を使用する場合は、.vscode/mcp.json に追加します。

{
  "servers": {
    "google-calendar-mcp-server": {
      "type": "stdio",
      "command": "node",
      "args": ["./dist/index.js"]
    }
  }
}

認証の設定

1. サービスアカウントの作成：
   • Google Cloud Console にアクセスします。
   • IAM & Admin > サービスアカウントに移動します。
   • 新しいサービスアカウントを作成します。
   • JSONキーファイルをダウンロードします。
2. カレンダーアクセスの共有：
   • Google Calendarを開きます。
   • カレンダー設定に移動します。
   • サービスアカウントのメールアドレスでカレンダーを共有します。
   • 「イベントの変更」権限を付与します。
3. 環境の設定：
   • JSONキーファイルをプロジェクトディレクトリに配置します。
   • .env ファイルを正しいパスで更新します。

📚 ドキュメント

利用可能なツール

list_events

様々なフィルタリングオプションを使用してGoogle Calendarからイベントを取得します。

パラメーター:

• calendarId (オプション): カレンダーID (デフォルト: "primary")
• timeMin (オプション): イベント開始時間の下限 (RFC3339タイムスタンプ)
• timeMax (オプション): イベント開始時間の上限 (RFC3339タイムスタンプ)
• maxResults (オプション): イベントの最大数 (デフォルト: 250)
• singleEvents (オプション): 繰り返しイベントを展開する (デフォルト: true)
• orderBy (オプション): イベントを "startTime" または "updated" で並べ替える

create_event

Google Calendarに新しいイベントを作成します。

パラメーター:

• calendarId (オプション): カレンダーID (デフォルト: "primary")
• summary (必須): イベントのタイトル
• description (オプション): イベントの説明
• start (必須): 開始日時オブジェクト (dateTimeとオプションのtimeZone)
• end (必須): 終了日時オブジェクト (dateTimeとオプションのtimeZone)
• location (オプション): イベントの場所
• attendees (オプション): 参加者オブジェクトの配列 (emailとdisplayName)
• recurrence (オプション): 繰り返しイベントのRRULE文字列の配列

update_event

既存のカレンダーイベントを更新します。

パラメーター:

• calendarId (オプション): カレンダーID (デフォルト: "primary")
• eventId (必須): 更新するイベントのID
• summary (オプション): 新しいイベントのタイトル
• description (オプション): 新しいイベントの説明
• start (オプション): 新しい開始日時
• end (オプション): 新しい終了日時
• location (オプション): 新しいイベントの場所
• attendees (オプション): 新しい参加者のリスト

delete_event

Google Calendarからイベントを削除します。

パラメーター:

• calendarId (オプション): カレンダーID (デフォルト: "primary")
• eventId (必須): 削除するイベントのID

list_calendars

認証されたユーザーが利用可能なGoogleカレンダーの一覧を取得します。

パラメーター:

• minAccessRole (オプション): 最小アクセスロールのフィルター
• showDeleted (オプション): 削除されたカレンダーを含める (デフォルト: false)
• showHidden (オプション): 非表示のカレンダーを含める (デフォルト: false)

プロジェクト構造

src/
├── index.ts          # メインのMCPサーバー実装
├── types/            # TypeScriptの型定義
└── utils/            # ユーティリティ関数

.env.example          # 環境変数のテンプレート
tsconfig.json         # TypeScriptの設定
package.json          # Node.jsの依存関係とスクリプト

新しいツールの追加

1. 入力検証用のZodスキーマを定義します。
2. ToolSchema定義を作成します。
3. 非同期ハンドラー関数を実装します。
4. ツールをサーバーに登録します。
5. 包括的なエラーハンドリングを追加します。

エラーハンドリング

すべてのツールは構造化されたレスポンスを返します。

// 成功レスポンス
{
  content: [{ type: "text", text: JSON.stringify(result) }]
}

// エラーレスポンス
{
  content: [{ type: "text", text: JSON.stringify(error) }],
  isError: true
}

🔧 技術詳細

• サーバーはNode.jsとTypeScriptで構築されています。
• Google Calendar APIとの通信にはOAuth認証を使用しています。
• 入力検証にはZodを使用しています。
• エラーハンドリングは構造化されたレスポンスを返すことで行われます。

📄 ライセンス

このプロジェクトはMITライセンスの下で公開されています。詳細は LICENSE ファイルを参照してください。

サポート

問題や質問については以下を参照してください。

• Google Calendar APIドキュメント を確認します。
• MCP仕様 を確認します。
• このリポジトリで問題を報告します。