Google Calendar MCP Server

Google カレンダー MCP サーバー

🔔 バージョンアップデートのお知らせ 🔔
バージョン1.0.5では、 createEventとupdateEventツールの両方で、 recurrenceパラメータを使用して定期的なイベントを作成できるようになりました。これにより、作成後に手動で設定する必要なく、定期的なイベントを直接作成および変更できるようになります。

プロジェクト概要

Google カレンダー MCP サーバーは、Google カレンダーと Claude Desktop の連携を可能にする MCP（モデルコンテキストプロトコル）サーバー実装です。このプロジェクトにより、Claude はユーザーの Google カレンダーと連携し、自然言語による対話を通じてカレンダーイベントの表示、作成、更新、削除が可能になります。

コア機能

• Google カレンダーの統合: Claude Desktop と Google カレンダー API 間の橋渡しを提供します
• MCP実装: AIアシスタントツール統合のためのモデルコンテキストプロトコル仕様に準拠
• OAuth2認証: Google API認証フローを安全に処理します
• イベント管理: 包括的なカレンダー イベント操作 (取得、作成、更新、削除) をサポートします。
• 色のサポート: colorIdパラメータを使用してイベントの色を設定および更新する機能
• STDIOトランスポート:Claude Desktopとの通信に標準入出力を使用します

技術アーキテクチャ

このプロジェクトでは以下を使用します:

• TypeScript : 型安全なコード開発用
• MCP SDK : Claude Desktop との統合には@modelcontextprotocol/sdkを使用します
• Google API : Google カレンダー API アクセスにgoogleapis使用します
• Zod : リクエスト/レスポンスデータのスキーマ検証を実装します
• 環境ベースの構成:構成管理にdotenvを使用する
• Helmet.js : セキュリティヘッダー用
• AES-256-GCM : トークン暗号化用
• Jest :ユニットテストとカバレッジ用
• GitHub Actions ：CI/CD向け

主なコンポーネント

1. MCP サーバー: Claude Desktop との通信を処理するコア サーバーの実装
2. Google カレンダー ツール: カレンダーの操作 (取得、作成、更新、削除)
3. 認証ハンドラ: Google API を使用した OAuth2 フローの管理
4. スキーマ検証: すべての操作におけるデータの整合性の確保
5. トークンマネージャー:認証トークンの安全な取り扱い

利用可能なツール

この MCP サーバーは、Google カレンダーとやり取りするための次のツールを提供します。

1. getEvents

さまざまなフィルタリング オプションを使用してカレンダー イベントを取得します。

パラメータ:

• calendarId (オプション): カレンダーID (省略した場合はプライマリカレンダーを使用)
• timeMin (オプション): イベント取得の開始時刻 (ISO 8601 形式、例: "2025-03-01T00:00:00Z")
• timeMax （オプション）: イベント取得の終了時刻（ISO 8601形式）
• maxResults (オプション): 取得するイベントの最大数 (デフォルト: 10)
• orderBy (オプション): 並べ替え順序 ("startTime" または "updated")

2. イベントを作成する

新しいカレンダー イベントを作成します。

パラメータ:

• calendarId (オプション): カレンダーID (省略した場合はプライマリカレンダーを使用)
• event : 次の内容を含むイベント詳細オブジェクト:
  • summary （必須）: イベントのタイトル
  • description （オプション）: イベントの説明
  • location （オプション）: イベントの場所
  • start : 開始時刻オブジェクト:
    • dateTime （オプション）: ISO 8601形式（例："2025-03-15T09:00:00+09:00"）
    • date （オプション）：終日イベントの場合はYYYY-MM-DD形式
    • timeZone (オプション): タイムゾーン (例: "Asia/Tokyo")
  • end : 終了時刻オブジェクト（startと同じ形式）
  • attendees （オプション）: メールアドレスとオプションの表示名を持つ出席者の配列
  • colorId (オプション): イベントカラーID (1-11)
  • recurrence （オプション）：RFC5545形式の繰り返しルールの配列（例：["RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR"]）

3. 更新イベント

既存のカレンダーイベントを更新します。この関数はまず既存のイベントデータを取得し、更新リクエストに含まれていないフィールドを保持しながら更新データとマージします。

パラメータ:

• calendarId (オプション): カレンダーID (省略した場合はプライマリカレンダーを使用)
• eventId (必須): 更新するイベントのID
• event : 更新するフィールドを含むイベント詳細オブジェクト（createEventと同じ構造、すべてのフィールドはオプション）
  • 明示的に指定されたフィールドのみが更新されます
  • 更新リクエストに含まれていないフィールドは既存の値を保持します
  • これにより、データを失うことなく部分的な更新が可能になります。
  • recurrenceパラメータを更新して、定期的なイベントパターンを変更できます。

4. イベントの削除

カレンダーイベントを削除します。

パラメータ:

• calendarId (オプション): カレンダーID (省略した場合はプライマリカレンダーを使用)
• eventId (必須): 削除するイベントのID

5. 認証する

Googleカレンダーの再認証を行います。これは、Claudeを再起動せずに複数のGoogleアカウントを切り替えたい場合に便利です。

パラメータ:

• なし

開発ガイドライン

新しい機能を追加したり、コードを変更したり、バグを修正したりする際は、 npm versionコマンドを使用して、変更ごとにバージョン番号を明示的に増加させてください。また、コーディングが明確で、OOP などの必要なコーディングルールをすべて遵守していることを確認してください。バージョンが更新されると、バージョンスクリプトは自動的にnpm installを実行しますが、提出する前にコードをビルドし、lint を実行してテストする必要があります。

コード構造

• src/ : ソースコードディレクトリ
  • auth/ : 認証処理
  • config/ : 構成設定
  • mcp/ : MCPサーバーの実装
  • tools/ : Google カレンダーツールの実装
  • utils/ : ユーティリティ関数とヘルパー

ベストプラクティス

• TypeScriptのベストプラクティスに従った適切な型付け
• 包括的なエラー処理の維持
• 適切な認証フローを確保する
• 依存関係を最新の状態に保つ
• すべての機能について明確なドキュメントを作成する
• セキュリティのベストプラクティスを実装する
• OAuth 2.1認証標準に従う
• すべての入出力データにスキーマ検証を使用する

テスト

• コア機能のユニットテストを実装する
• 認証フローを徹底的にテストする
• Google API によるカレンダー操作の検証
• カバレッジレポートを使用してテストを実行する
• セキュリティテストが含まれていることを確認する

展開

このパッケージは、npm で@takumi0706/google-calendar-mcpとして公開されています。

前提条件

1. Google Cloud プロジェクトを作成し、Google カレンダー API を有効にする
2. Google Cloud Console で OAuth2 認証情報を構成する
3. 環境変数を設定します。

クロードデスクトップ構成

claude_desktop_config.jsonにサーバーを追加してください。localhost にアクセスできない環境で実行している場合は、 USE_MANUAL_AUTH環境変数を「true」に設定してください。

セキュリティに関する考慮事項

• OAuth トークンはメモリにのみ保存されます（ファイルベースのストレージには保存されません）
• 機密性の高い認証情報は環境変数として提供する必要があります
• 安全な保管のためにAES-256-GCMを使用したトークン暗号化
• 明示的な code_verifier と code_challenge 生成によるPKCE 実装
• CSRF 保護のための状態パラメータ検証
• Helmet.js を使用して適用されたセキュリティ ヘッダー
• APIエンドポイント保護のレート制限
• Zodスキーマによる入力検証

詳細については、 SECURITY.mdを参照してください。

メンテナンス

• Google カレンダー API との互換性を維持するための定期的な更新
• バージョンアップデートはREADME.mdに記載されています

トラブルシューティング

問題が発生した場合:

1. Google OAuth認証情報が正しく設定されていることを確認してください
2. Google カレンダー API アクセスに十分な権限があることを確認してください
3. Claude Desktop の設定が正しいことを確認してください

よくあるエラー

• JSON解析エラー： Unexpected non-whitespace character after JSON at position 4 (line 1 column 5)あります」といったエラーが表示される場合、通常はJSON-RPCメッセージの形式が不正です。この問題はバージョン0.6.7以降で修正されています。それでもこれらのエラーが発生する場合は、最新バージョンに更新してください。
• 認証エラー: Google OAuth 認証情報を確認してください
• 無効な状態パラメータ：再認証時にAuthentication failed: Invalid state parameter表示される場合は、OAuthサーバーのライフサイクル管理を修正したバージョン1.0.3以降にアップデートしてください。それより古いバージョンでは、ポート4153を閉じてアプリケーションを再起動する必要がある場合があります。
• 接続エラー: サーバーのインスタンスが1つだけ実行されていることを確認してください
• 切断の問題: カスタム TCP ソケットを使用せずにサーバーが MCP メッセージを適切に処理していることを確認します。
• localhost にアクセスできません: localhost にアクセスできない環境（リモートサーバーやコンテナなど）でアプリケーションを実行している場合は、 USE_MANUAL_AUTH=trueを設定して手動認証を有効にしてください。これにより、アプリケーションの認証後に Google から表示される認証コードを手動で入力できるようになります。

バージョン履歴

バージョン1.0.6の変更点

• この Google カレンダー MCP サーバーではスコープが必要ないことを修正しました

バージョン1.0.5の変更点

• createEventおよびupdateEventツールの両方で、 recurrenceパラメータを通じて定期的なイベントのサポートを追加しました。
• 手動設定なしで定期的なイベントを直接作成および変更できます

バージョン1.0.4の変更点

• バージョン番号の更新を伴うメンテナンスリリース
• バージョン1.0.3から機能変更はありません
• 最新の依存関係との互換性を確保

バージョン1.0.3の変更点

• Claude を再起動せずに再認証を可能にする新しいauthenticateツールを追加しました
• セッション中に異なるGoogleアカウントを切り替えることが可能になりました
• MCP インターフェースを通じて公開された認証機能
• アカウント切り替え時に再起動する必要がなくなり、ユーザーエクスペリエンスが向上しました
• ローカルホストにアクセスできない環境向けに手動認証オプションを追加しました
• 認証コードを手動で入力するためのreadlineインターフェースを実装しました
• 手動認証を有効にするために USE_MANUAL_AUTH 環境変数を追加しました
• zod 依存関係を最新バージョン (3.24.2) に更新しました
• 最新の zod 機能によるスキーマ検証の改善
• コードの安定性とセキュリティの強化
• 再認証中に発生する「無効な状態パラメータ」エラーを修正しました
• OAuth サーバーをオンデマンドで起動し、認証後にシャットダウンするように変更しました
• ポートの競合を防ぐためのサーバーライフサイクル管理の改善
• 認証フローのエラー処理の強化

バージョン1.0.2の変更点

• 部分的な更新を実行するときに既存のイベントデータを保持するようにupdateEvent関数を修正しました。
• 更新前に既存のイベントデータを取得するためのgetEvent関数を追加しました
• データの損失を防ぐために更新データと既存のデータをマージするようにupdateEventを変更しました
• 更新リクエストのすべてのフィールドをオプションにするためにスキーマ検証を更新しました
• updateEvent関数のドキュメントの改善

バージョン1.0.1の変更点

• Node.js v20.9.0+ と 'open' パッケージ (v10+) との互換性の問題を修正しました
• ESM のみの「オープン」パッケージの静的インポートを動的インポートに置き換えました
• OAuth認証中にブラウザを開く際のエラー処理の改善
• 保守性を向上させるためのコードコメントの強化

バージョン1.0.0の変更点

• 生産準備完了を示すメジャーバージョンリリース
• 保守性を向上させる包括的なコードリファクタリング
• すべてのメッセージとコメントの国際化（日本語から英語への翻訳）
• コードの一貫性と可読性の向上
• ユーザーエクスペリエンスを向上させるためにエラーメッセージを改善しました
• プロジェクトの現在の状態を反映するようにドキュメントを更新しました
• コードベース全体で標準化されたコーディングスタイル

バージョン0.8.0の変更点

• リフレッシュトークンの問題を処理するための強化された OAuth 認証フロー
• Google に同意画面を表示させ、新しいリフレッシュ トークンを提供するよう強制するprompt: 'consent'パラメータを追加しました
• リフレッシュトークンが利用できない場合はアクセストークンのみで動作するように認証フローを変更しました
• リフレッシュ トークンがない場合やリフレッシュ トークンが無効な場合を処理するためにトークン リフレッシュ ロジックを改善しました
• トークン管理を改善するために、更新されたアクセストークンを保存するトークンストレージを更新しました
• トークン更新ロジックにおける潜在的な無限ループを修正しました

発達

このプロジェクトに貢献するには:

テスト

テストを実行するには:

ライセンス

マサチューセッツ工科大学