Google カレンダー MCP サーバー

🔔 バージョンアップデートのお知らせ 🔔
バージョン1.0.2には、部分更新時に既存のイベントデータを保持するためのupdateEvent関数の修正が含まれています。バージョン1.0.1には、Node.js v20.9.0以降と「open」パッケージの互換性に関する修正が含まれています。このパッケージは現在、バージョン10以降ではESMのみで利用可能です。バージョン1.0.0は、包括的なコードリファクタリングと国際化を実施した、最初の本番環境対応リリースとなります。

プロジェクト概要

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)

3. 更新イベント

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

パラメータ:

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

4. イベントの削除

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

パラメータ:

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

開発ガイドライン

新しい機能を追加したり、コードを変更したり、バグを修正したりする際は、 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にサーバーを追加します。

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

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

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

メンテナンス

• Google カレンダー API との互換性を維持するための定期的な更新
• バージョンアップデートはREADME.mdに記載されています
• ログはユーザーのホームディレクトリ~/.google-calendar-mcp/logs/に保存されます。

トラブルシューティング

問題が発生した場合:

1. ホームディレクトリの~/.google-calendar-mcp/logs/にあるログを確認してください。
2. Google OAuth認証情報が正しく設定されていることを確認してください
3. Google カレンダー API アクセスに十分な権限があることを確認してください
4. Claude Desktop の設定が正しいことを確認してください

よくあるエラー

• JSON解析エラー： Unexpected non-whitespace character after JSON at position 4 (line 1 column 5)あります」といったエラーが表示される場合、通常はJSON-RPCメッセージの形式が不正です。この問題はバージョン0.6.7以降で修正されています。それでもこれらのエラーが発生する場合は、最新バージョンに更新してください。
• 認証エラー: Google OAuth 認証情報を確認してください
• 接続エラー: サーバーのインスタンスが1つだけ実行されていることを確認してください
• 切断の問題: カスタム TCP ソケットを使用せずにサーバーが MCP メッセージを適切に処理していることを確認します。

バージョン履歴

バージョン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'パラメータを追加しました
• リフレッシュトークンが利用できない場合はアクセストークンのみで動作するように認証フローを変更しました
• リフレッシュ トークンがない場合やリフレッシュ トークンが無効な場合を処理するためにトークン リフレッシュ ロジックを改善しました
• トークン管理を改善するために、更新されたアクセストークンを保存するトークンストレージを更新しました
• トークン更新ロジックにおける潜在的な無限ループを修正しました

発達

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

テスト

テストを実行するには:

ライセンス

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