Google Calendar MCP Server

Google Calendar MCP Server

🔔 バージョン更新のお知らせ 🔔
バージョン 2.0.0 では MCP プロトコルのリビジョン 2026-07-28 に移行し、OAuth フローに PKCE を実装します。 Node.js 20 以降が必要です。変更点の全一覧については、以下のバージョン履歴をご覧ください。

プロジェクト概要

Google Calendar MCP Server は、Google Calendar と Claude Desktop の連携を可能にする MCP（Model Context Protocol）サーバーの実装です。このプロジェクトにより、Claude はユーザーの Google Calendar を操作でき、自然言語でのやり取りを通じて、カレンダーの予定の表示、作成、更新、削除が可能になります。

主な機能

• Google Calendar との連携：Claude Desktop と Google Calendar API の橋渡しを行います
• MCP の実装：AI アシスタントのツール連携に関する Model Context Protocol の仕様に準拠しています
• OAuth2 認証：Google API の認証フローを安全に処理します
• 予定の管理：カレンダーの予定に関する包括的な操作（取得、作成、更新、削除）に対応します
• 色のサポート：colorId パラメーターを使って予定の色を設定、更新できます
• STDIO トランスポート：Claude Desktop との通信に標準入力／出力を使用します

技術アーキテクチャ

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

• TypeScript：型安全なコード開発に使用します
• MCP SDK：@modelcontextprotocol/server v2 を使用します（プロトコルリビジョン 2026-07-28。古いクライアント向けに 2025 年のリビジョンも引き続き提供されます）
• Google API：Google Calendar API へのアクセスに googleapis を使用します
• Hono：認証サーバー向けの軽量で高速な Web フレームワークです
• google-auth-library：PKCE（S256）を使った OAuth2 認可コードフローを実行します
• Zod：リクエスト／レスポンスデータのスキーマ検証を実装します
• 環境変数ベースの設定：設定管理に dotenv を使用します
• AES-256-GCM：Node.js の crypto モジュールを使ったトークン暗号化に使用します
• Open：認証中にブラウザーを自動的に起動します
• Readline：サーバー環境での手動認証入力に使用します
• Jest：単体テストとカバレッジに使用します
• GitHub Actions：CI/CD に使用します

主なコンポーネント

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

利用可能なツール

この MCP サーバーでは、Google Calendar と連携するために以下のツールを利用できます。

1. getEvents

さまざまなフィルター条件を指定して、カレンダーの予定を取得します。

パラメーター：

• calendarId（省略可能）：カレンダー ID（省略した場合、空文字列、null、または undefined の場合はメインカレンダーを使用します）
• timeMin（省略可能）：予定取得の開始時刻（ISO 8601 形式、例："2025-03-01T00:00:00Z"）。空文字列、null、または undefined の値は無視されます
• timeMax（省略可能）：予定取得の終了時刻（ISO 8601 形式）。空文字列、null、または undefined の値は無視されます
• maxResults（省略可能）：取得する予定の最大数（デフォルト：10）
• orderBy（省略可能）：並べ替え順（"startTime" または "updated"）。空文字列、null、または undefined の場合は、デフォルトで "startTime" になります

2. createEvent

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

パラメーター：

• 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：終了時刻オブジェクト（開始時刻と同じ形式）
  • attendees（任意）：メールアドレスと任意の表示名を含む参加者の配列
  • colorId（任意）：イベントの色 ID（1-11）
  • recurrence（任意）：RFC5545 形式の繰り返しルールの配列（例：["RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR"]）

3. updateEvent

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

パラメーター：

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

4. deleteEvent

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

パラメーター：

• calendarId（任意）：カレンダー ID（省略した場合はメインのカレンダーを使用します）
• eventId（必須）：削除するイベントの ID

5. authenticate

Google Calendar で再認証します。Claude を再起動せずに異なる Google アカウントを切り替えたい場合に便利です。

パラメーター：

• なし

開発ガイドライン

新しい関数の追加、コードの変更、バグの修正を行う場合は、npm version コマンドを使用して、変更ごとにバージョンをセマンティックに更新してください。 また、コードが明確で、OOP などの必要なコーディング規則に従っていることを確認してください。 バージョンスクリプトはバージョン更新時に自動的に npm install を実行しますが、提出前にコードをビルドし、lint とテストも実行してください。

コード構成

• src/：ソースコードディレクトリ
  • auth/：認証処理（PKCE による OAuth フロー、トークンの保存）
  • calendar/：Google Calendar API との連携
  • config/：設定と検証
  • mcp/：MCP サーバーの実装
    • tools/：Google Calendar ツールのハンドラー
  • utils/：ユーティリティ関数とヘルパー

ベストプラクティス

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

テスト

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

デプロイ

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

npx @takumi0706/[email protected]

前提条件

0. Node.js 20 以降
1. Google Cloud プロジェクトを作成し、Google Calendar API を有効にします
2. Google Cloud Console で OAuth2 認証情報を設定します
3. 環境変数を設定します：

# Create a .env file with your Google OAuth credentials
GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
GOOGLE_REDIRECT_URI=http://localhost:4153/oauth2callback
# Optional: Token encryption key (auto-generated if not provided)
TOKEN_ENCRYPTION_KEY=32-byte-hex-key
# Optional: Auth server port and host (default port: 4153, host: localhost)
AUTH_PORT=4153
AUTH_HOST=localhost
# Optional: MCP server port and host (default port: 3000, host: localhost)
PORT=3000
HOST=localhost
# Optional: Enable manual authentication (useful when localhost is not accessible)
USE_MANUAL_AUTH=true

Claude Desktop の設定

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

{
  "mcpServers": {
    "google-calendar": {
      "command": "npx",
      "args": [
        "-y",
        "@takumi0706/google-calendar-mcp"
      ],
      "env": {
        "GOOGLE_CLIENT_ID": "your_client_id",
        "GOOGLE_CLIENT_SECRET": "your_client_secret",
        "GOOGLE_REDIRECT_URI": "http://localhost:4153/oauth2callback"
      }
    }
  }
}

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

• OAuth トークンはメモリ内にのみ保存されます（ファイルベースのストレージには保存されません）。再起動すると失われるため、再起動のたびに再認証が必要です。
• 機密性の高い認証情報は環境変数として指定する必要があります
• トークンがメモリ内にある間は、AES-256-GCM を使用してトークンを暗号化します。ただし、鍵は暗号文と同じプロセス内に存在するため、プロセスメモリを気軽に調べる行為への保護にはなりますが、すでにこのプロセスのメモリを読み取れる攻撃者に対する保護にはなりません。
• 認可コードフローで **PKCE（S256）**を使用します。リクエストごとにcode_verifierを生成し、認可エンドポイントには送信しません
• CSRF 保護のためのstate パラメーターの検証：256 ビットの CSPRNG state を使用し、一定時間で比較します。state は使い捨てで、10 分後に期限切れとなります
• リクエストのHostヘッダーではなく、設定から取得した固定のリダイレクト URI
• Zod スキーマによる入力検証
• OAuth の結果ページに補間されるすべての値に対するHTML エスケープ

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

メンテナンス

• Google Calendar API との互換性を保つため、定期的に更新します
• バージョンの更新内容は README.md に記載されています

トラブルシューティング

問題が発生した場合は、次の点を確認してください。

1. Google OAuth の認証情報が正しく設定されていることを確認します
2. Google Calendar 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 の認証情報を確認してください
• 無効な state パラメーター：再認証時にAuthentication failed: Invalid state parameterと表示される場合は、OAuth サーバーのライフサイクル管理が修正されたバージョン 1.0.3 以降に更新してください。古いバージョンでは、ポート 4153 を閉じてアプリケーションを再起動する必要がある場合があります。
• 接続エラー：サーバーのインスタンスが 1 つだけ実行されていることを確認してください
• 切断の問題：カスタム TCP ソケットを使用せず、サーバーが MCP メッセージを適切に処理していることを確認してください
• localhost にアクセスできない：リモートサーバーやコンテナーなど、localhost にアクセスできない環境でアプリケーションを実行している場合は、USE_MANUAL_AUTH=trueを設定して手動認証を有効にしてください。これにより、アプリケーションの認可後に Google が表示する認可コードを手動で入力できます。
• MCP パラメーターの検証エラー：空文字列のパラメーターでエラー -32602 が表示される場合は、空文字列、null、undefined の値を適切に処理するバージョン 1.0.7 以降に更新してください。

バージョン履歴

バージョン 2.0.0 の変更点

セキュリティ

• OAuth 認可コードフローに PKCE（S256）を実装しました。以前のバージョンでは PKCE の説明がありましたが、code_challenge は送信されていませんでした。
• state パラメーターは、256 ビットの CSPRNG 値になり、定数時間で比較され、1 回のみ使用でき、10 分後に有効期限が切れるようになりました。以前は Math.random() で生成されていました。
• OAuth エラーページのリフレクション型 XSS を修正しました。エラーの詳細は HTML に埋め込まずにログに記録し、埋め込むすべての値をエスケープするようになりました。
• redirect_uri はリクエストの Host ヘッダーから導出せず、設定値に固定されるようになりました。
• ローカル認可サーバーは、ポートがすでに使用されている場合、別のインスタンスがフローを処理していると仮定せず、処理を中止するようになりました。
• TOKEN_ENCRYPTION_KEY は正確に 64 桁の 16 進数である必要があり、無効なキーとすべてゼロのキーは起動時に拒否されるようになりました。
• 本番環境の依存関係にある既知の脆弱性をすべて解決しました。

プロトコル

• @modelcontextprotocol/server v2 とプロトコルリビジョン 2026-07-28 に移行しました。2025 年のリビジョンも引き続き提供されるため、既存のクライアントは引き続き動作します。
• tools/list が実際のスキーマを通知するようになり、createEvent の event 引数などのネストされたオブジェクトのプロパティも公開されるようになりました。以前は内容が不明瞭でした。
• prompts/get を実装しました。サーバーは取得できないプロンプトを 10 個通知していました。
• resources/read が仕様で求められる形式を返すようになりました。
• initialize が capabilities を通じて Zod の内部情報を漏えいしなくなりました。

破壊的変更

• Node.js 20 以降が必要です。

その他

• ツールチェーンを pnpm に移行し、googleapis、hono、zod をアップグレードし、@hono/oauth-providers を削除しました。
• 配布コードから any と型アサーションを削除し、lint で強制するようにしました。

バージョン 1.0.7 の変更点

• MCP ツールのパラメーター検証を強化し、空文字列、null、undefined の値を適切に処理するようにしました
• 空文字列のパラメーターを getEvents ツールに渡した際に発生する MCP エラー -32602 を修正しました
• preprocessArgs 関数を改善して空の値をスキップし、Zod スキーマのデフォルト値が正しく適用されるようにしました
• 空のパラメーターの処理に関する包括的なテストカバレッジを追加しました

バージョン 1.0.6 の変更点

• この Google カレンダー MCP サーバーではスコープが不要である問題を修正しました

バージョン 1.0.5 の変更点

• createEvent ツールと updateEvent ツールの両方で recurrence パラメーターを使った定期的なイベントのサポートを追加しました
• 手動で設定することなく、定期的なイベントを直接作成・変更できるようになりました

バージョン 1.0.4 の変更点

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

バージョン 1.0.3 の変更点

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

バージョン 1.0.2 の変更点

• 部分更新の実行時に既存のイベントデータが保持されるよう、updateEvent 関数を修正しました
• 更新前に既存のイベントデータを取得する getEvent 関数を追加しました
• データの損失を防ぐため、updateEvent が更新データと既存データをマージするよう変更しました
• 更新リクエストではすべてのフィールドを省略可能にするよう、スキーマ検証を更新しました
• updateEvent 関数のドキュメントを改善しました

バージョン 1.0.1 の変更点

• Node.js v20.9.0 以降と 'open' パッケージ（v10 以降）の互換性問題を修正しました
• ESM 専用の 'open' パッケージの静的インポートを動的インポートに置き換えました
• OAuth 認証中にブラウザーを開く際のエラー処理を改善しました
• 保守性を高めるため、コードコメントを強化しました

バージョン 1.0.0 の変更点

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

バージョン 0.8.0 の変更点

• リフレッシュトークンの問題に対応できるよう、OAuth 認証フローを強化しました
• Google に同意画面を表示させて新しいリフレッシュトークンを取得できるよう、prompt: 'consent' パラメーターを追加しました
• リフレッシュトークンがない場合でも、アクセストークンだけで認証フローが機能するよう変更しました
• リフレッシュトークンがない場合や無効な場合に対応できるよう、トークンのリフレッシュロジックを改善しました
• トークン管理を改善するため、リフレッシュ後のアクセストークンを保存するよう、トークンの保存処理を更新しました
• トークンのリフレッシュロジックで発生する可能性のある無限ループを修正しました

インストール

クイックスタート（推奨）

npm から直接インストールします：

npm install -g @takumi0706/google-calendar-mcp

手動インストール

開発またはカスタマイズの場合：

# Clone the repository
git clone https://github.com/takumi0706/google-calendar-mcp.git
cd google-calendar-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run the server
npm start

本番環境へのデプロイ

本番環境で使用するには、有効な Google OAuth 認証情報が必要です。適切な認証情報がない場合、セキュリティ要件への準拠を確実にするため、サーバーは起動に失敗します。

テスト

テストを実行するには：

# Run all tests
npm test

# Run tests with coverage report
npm test -- --coverage

ライセンス

MIT