Google カレンダー MCP サーバー

これは、Googleカレンダーとの統合を実現するモデルコンテキストプロトコル（MCP）サーバーです。LLMは、標準化されたインターフェースを通じてカレンダーイベントの読み取り、作成、更新、検索を行うことができます。

使用例

カレンダー統合に期待される通常の機能に加えて、次のような非常に動的な複数ステップのプロセスも実行できます。

スクリーンショットや画像からイベントを追加します。
Add this event to my calendar based on the attached screenshot.
サポートされている画像形式: PNG、JPEG、GIF 画像には、日付、時間、場所、説明などのイベントの詳細を含めることができます
カレンダー分析:
What events do I have coming up this week that aren't part of my usual routine?
出席確認:
Which events tomorrow have attendees who have not accepted the invitation?
自動座標イベント:
Here's some available that was provided to me by someone. Take a look at the available times and create an event that is free on my work calendar.
ご自身の空き時間を入力してください:
Please provide availability looking at both my personal and work calendar for this upcoming week. Choose times that work well for normal working hours on the East Coast. Meeting time is 1 hour

要件

Node.js (最新 LTS を推奨)
TypeScript 5.3以上
カレンダー API が有効になっている Google Cloud プロジェクト
OAuth 2.0 認証情報 (クライアント ID とクライアントシークレット)

Google Cloud のセットアップ

Google Cloud Consoleにアクセスします
新しいプロジェクトを作成するか、既存のプロジェクトを選択します。
プロジェクトでGoogleカレンダーAPIを有効にしてください。APIを有効にする前に、上部のバーで適切なプロジェクトが選択されていることを確認してください。
OAuth 2.0 認証情報を作成します。
- 資格情報へ移動
- 「認証情報を作成」>「OAuthクライアントID」をクリックします
- アプリがアクセスするデータの種類として「ユーザーデータ」を選択します
- アプリ名と連絡先情報を追加します
- 次のスコープを追加します (オプション)。
  - https://www.googleapis.com/auth/calendar.events (または必要に応じてより広範なhttps://www.googleapis.com/auth/calendar )
- アプリケーションの種類として「デスクトップアプリ」を選択します (重要!)
- OAuth同意画面でテストユーザーとしてメールアドレスを追加します
  - 注: テストユーザーの追加には数分かかる場合があります。テストユーザーが登録されるまで、OAuth の同意は続行できません。
  - テストモードに関する注意: アプリがテストモードの場合、認証トークンは 1 週間後に期限切れになり、 npm run authを実行して更新する必要があります。

インストール

リポジトリをクローンする
依存関係をインストールします (これにより、postinstall 経由で js もビルドされます)。
npm install
Google Cloud Console (「認証情報」の下) から Google OAuth 認証情報をダウンロードし、ファイルの名前をgcp-oauth.keys.jsonに変更して、プロジェクトのルートディレクトリに配置します。
- ファイルに「デスクトップアプリ」の資格情報が含まれていることを確認します。
- または、提供されているテンプレートファイル ( cp gcp-oauth.keys.example.json gcp-oauth.keys.jsonをコピーし、Google Cloud Console からの認証情報を入力します。

利用可能なスクリプト

npm run build - TypeScript コードをビルドします ( srcをbuildにコンパイルします)
npm run typecheck - コンパイルせずにTypeScriptの型チェックを実行する
npm run start - コンパイルされた MCP サーバーを起動します ( node build/index.jsを使用)
npm run auth - Google OAuth 認証フローを手動で実行します。
npm test - Vitest を使用してユニット/統合テストスイートを実行する
npm run test:watch - ウォッチモードでテストを実行する
npm run coverage - テストを実行し、カバレッジレポートを生成する

認証

サーバーは、カレンダーデータにアクセスするために Google OAuth 2.0 認証を処理します。

自動認証フロー（サーバー起動時）

gcp-oauth.keys.jsonに正しい名前が付けられ、プロジェクトルートに配置されていることを確認します。
MCP サーバーを起動します: npm start 。
サーバーは.gcp-saved-tokens.json内の既存の有効な認証トークンをチェックします。
有効なトークンが見つかった場合、サーバーは正常に起動します。
有効なトークンが見つからない場合:
- サーバーは一時的なローカル Web サーバーを起動しようとします (ポート 3000 ～ 3004 を試行)。
- デフォルトのウェブブラウザが自動的に開き、Google アカウントのログインと同意画面が表示されます。
- ブラウザの指示に従ってアプリケーションを承認します。
- 承認が成功すると、ローカルページ (例: http://localhost:3000/oauth2callback ) にリダイレクトされます。
- このページには、トークンが.gcp-saved-tokens.jsonに保存されたことを確認する成功メッセージが表示されます (正確なファイルパスも表示されます)。
- 一時認証サーバーは自動的にシャットダウンします。
- メイン MCP サーバーは起動プロセスを続行します。

手動認証フロー

再認証が必要な場合、または認証を個別に処理したい場合は、次の手順を実行します。

コマンドを実行します: npm run auth
このスクリプトは、上記で説明したものと同じブラウザベースの認証フローを実行します。
ブラウザが開き、承認すると、トークンが保存された場所を示す成功ページが表示されます。
認証が成功するとスクリプトは自動的に終了します。

トークン管理

認証トークンは、プロジェクトルートの.gcp-saved-tokens.jsonに保存されます。
このファイルは自動的に作成され、バージョン管理にコミットしないでください ( .gitignoreに含まれています)。
サーバーは、保存されているリフレッシュトークンを使用して、期限切れのアクセストークンを自動的に更新しようとします。
リフレッシュトークン自体の有効期限が切れた場合（たとえば、Google Cloud アプリがテストモードの場合は 7 日後）、または取り消された場合は、自動フロー（サーバーを再起動する）または手動のnpm run authコマンドを使用して再認証する必要があります。

テスト

ユニットテストと統合テストはVitestを使用して実装されます。

テストを実行: npm test
ウォッチモードでテストを実行する: npm run test:watch
カバレッジレポートを生成する: npm run coverage

サーバーのロジックとハンドラーの分離されたテストを確実に実行するために、模擬外部依存関係（Google API、ファイルシステム）をテストします。

セキュリティノート

サーバーはローカルで実行され、OAuth 認証が必要です。
OAuth認証情報（ gcp-oauth.keys.json ）と保存済みトークン（ .gcp-saved-tokens.json ）はバージョン管理にコミットしないでください.gitignoreファイルに追加されていることを確認してください。
本番環境で使用する場合は、OAuth アプリケーションを Google で検証することを検討してください。

Claude Desktopでの使用

この設定をClaude Desktopの設定ファイルに追加します。例/Users/<user>/Library/Application Support/Claude/claude_desktop_config.json ：
{ "mcpServers": { "google-calendar": { "command": "node", "args": ["<absolute-path-to-project-folder>/build/index.js"] } } }
注: <absolute-path-to-project-folder>プロジェクトディレクトリへの実際のパスに置き換えます。
Claudeデスクトップを再起動します

発達

トラブルシューティング

認証エラー / コールバック時の接続リセット:
- gcp-oauth.keys.jsonが存在し、デスクトップアプリタイプの認証情報が含まれていることを確認します。
- Google Cloud OAuth 同意画面の設定で、ユーザーのメールがテストユーザーとして追加されていることを確認します (変更が反映されるまで数分かかる場合があります)。
- .gcp-saved-tokens.jsonを削除して再認証してみてください（ npm run authまたは restart npm start ）。
- 認証が必要な場合、他のプロセスがポート 3000 ～ 3004 をブロックしていないことを確認します。
トークンは毎週期限切れになります:
- Google Cloud アプリがテストモードの場合、更新トークンは 7 日後に期限切れになります。必要に応じて再認証してください。
- より長い有効期間の更新トークンを取得するには、Google Cloud Console でアプリを本番環境に移行することを検討してください（Google による検証が必要です）。
ビルドエラー:
- npm install再度実行します。
- Node.js のバージョンを確認します (LTS を使用します)。
- build/ディレクトリを削除し、 npm run buildを実行します。

ライセンス

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

google-calendar-mcp

Integrations