Google Calendar MCP Server

Google Calendar MCP サーバー

Claude Desktop が Google Calendar に接続して操作できるようにする、TypeScript ベースの Model Context Protocol（MCP）サーバーです。

機能

• Claude Desktop AI を Google Calendar のデータに接続
• Google OAuth2 による認証
• カレンダーのリストと予定を取得
• カレンダーの予定を作成、更新、削除
• すべてのカレンダーの今後の予定を取得
• トークンを安全に処理
• 強い型付けを備えた TypeScript

必要条件

• Node.js（v16 以降）
• npm または yarn
• カレンダーにアクセスできる Google アカウント
• Google OAuth2 認証情報（Cloud OAuth 方式の場合）

インストール

1. リポジトリをクローンする

git clone https://github.com/Jackson88/google-calendar-mcp
cd google-calendar-mcp

2. 依存関係をインストールする

npm install
# or
yarn install

3. 環境変数を設定する

.env.example を基に .env ファイルを作成します。

cp .env.example .env

次に、設定内容に合わせて .env ファイルを編集します。

# Authentication Method Configuration
# -----------------------------
# Two authentication methods are available:
# 1. google_cloud - Uses Google Cloud OAuth (requires Google Cloud project setup)
# 2. direct - Uses direct authentication (simpler, doesn't require Google Cloud project)

# Choose one of the following authentication methods:
# AUTH_METHOD=google_cloud
AUTH_METHOD=direct

# Server Configuration
# -------------------
PORT=3000
NODE_ENV=development

# Google Calendar API (required only if AUTH_METHOD=google_cloud)
# --------------------------------------------------------------
# These credentials require a Google Cloud Platform project with Google Calendar API enabled
# You'll need to create OAuth credentials and configure the redirect URI in Google Cloud Console
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
GOOGLE_REDIRECT_URI=http://localhost:3000/auth/callback

# MCP Configuration
# ----------------
MCP_SERVER_ID=google-calendar-mcp
MCP_SERVER_NAME=Google Calendar Integration
MCP_SERVER_DESCRIPTION=Retrieves and manages Google Calendar events

認証方法

この MCP サーバーは、2 つの認証方法に対応しています。

1. Google Cloud OAuth（推奨）

これは、推奨される最も安全な方法です。Google Cloud プロジェクトと OAuth 認証情報の作成が必要ですが、最高のセキュリティとユーザーエクスペリエンスを提供します。

• OAuth 2.0 のベストプラクティスに準拠
• ユーザー認証情報を直接扱わない
• 本番環境での使用に最も信頼性が高い

Google Cloud OAuth を設定するには：

1. Google Cloud Console にアクセスします
2. 新しいプロジェクトを作成します
3. Google Calendar API を有効にします
4. OAuth2 認証情報を作成します（ウェブアプリケーションタイプ）
5. 承認済みリダイレクト URI を追加します：
   • 開発環境の場合：http://localhost:3000/auth/callback
   • 本番環境の場合：本番環境のコールバック URL

2. 直接認証（簡易方式）

個人利用や開発用途では、Google Cloud の設定が不要な簡易直接認証方式を使用できます。

• Google アカウントで直接認証
• 設定は簡単ですが、セキュリティと信頼性に制限があります
• 個人利用や開発用途に最適

直接認証を使用するには、.env ファイルに次のように設定します。

AUTH_METHOD=direct

注：直接認証は Google のセキュリティポリシーの対象となる場合があり、Google が認証要件を変更すると動作しなくなる可能性があります。

サーバーの実行

開発モード

# Start the development server with hot reloading
npm run dev
# or
yarn dev

本番モード

# Build the TypeScript code
npm run build
# or
yarn build

# Start the production server
npm run start
# or
yarn start

MCP 統合のための Claude の設定

Claude との互換性に関する重要な注意

⚠️ 現在の制限事項：2025 年 4 月時点では、Claude Desktop の MCP 接続への対応は限定的、または対応していない場合があります。テストでは、認証方法にかかわらず、現在のバージョンの Claude Desktop は外部 MCP サーバーに接続できないことが確認されています。以下の手順は、Claude Desktop が MCP サーバー接続に完全対応した場合に備えた参考情報です。

「外部サーバーに接続できません」というエラーメッセージが表示される場合、お使いのバージョンの Claude Desktop が現在、外部 MCP 接続に対応していないことを示しています。これは現在の Claude Desktop の実装上の制限であり、この MCP サーバーの問題ではありません。

前提条件

1. お使いのコンピューターに Claude Desktop がインストールされていること
2. Google Calendar MCP サーバーが実行中で、アクセス可能であること
3. お使いのバージョンの Claude Desktop が MCP 接続に対応していること

サーバーの実行

Claude に接続を依頼する前に、MCP サーバーを手動で起動する必要があります。Claude Desktop が npx やその他のコマンドを使ってサーバーを起動することはありません。

統合を設定するには、次の手順に従います。

1. MCP サーバーを起動します：

   # Development mode
   npm run dev
   
   # OR Production mode (after building)
   npm run build
   npm run start
   

2. Google で認証します（初回のみ）：

   • Google Cloud OAuth の場合：ブラウザーで http://localhost:3000/mcp/auth/url にアクセスし、認証フローを完了します
   • 直接認証の場合：Postman や curl などのツールを使い、認証情報を指定して http://localhost:3000/auth/direct に POST リクエストを送信します

直接認証方法

このサーバーは、Google Calendar との認証方法を 2 つサポートしています。Claude Desktop との接続がまだサポートされていない場合でも、どちらもサーバー API から直接使用できます。

1. Google Cloud OAuth（推奨）

標準的な OAuth フローを使用する、より安全な方法です。

1. ブラウザーで http://localhost:3000/mcp/auth/url にアクセスします
2. Google の認証手続きを完了します
3. コールバック URL にリダイレクトされます

2. 直接認証

Google Cloud を設定せずに開発やテストを行う場合：

# Using curl
curl -X POST http://localhost:3000/auth/direct \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"your_password"}'  

# Or with cookies
curl -X POST http://localhost:3000/auth/direct \
  -H "Content-Type: application/json" \
  -d '{"cookies":"your_google_cookies"}'  

これらの方法を使うと、Claude Desktop との接続がまだサポートされていない場合でも、サーバーの機能を直接テストできます。

Claude Desktop の設定

MCP サーバーを認識してアクセスできるように、Claude Desktop を設定する必要があります。

1. Claude Desktop の設定ファイルを探します：

   • macOS の場合：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows の場合：%APPDATA%\Claude\claude_desktop_config.json

2. MCP サーバーの設定を設定ファイルに追加します：

   • テキストエディターで settings.json ファイルを開きます
   • mcpServers セクションを探すか、新しく作成します
   • 次の設定を追加します（必要に応じて調整してください）：

    {
      "mcpServers": {
        "google-calendar": {
          "command": "npx",
          "args": ["-y", "google-calendar-mcp"],
          "env": {
            "GOOGLE_CLIENT_ID": "<your-client-id>",
            "GOOGLE_CLIENT_SECRET": "<your-client-secret>",
            "GOOGLE_REDIRECT_URI": "http://localhost:3000/auth/callback"
          },
          "description": "Google Calendar MCP server using npx"
        }
      }
    }
   

3. ファイルを保存して、Claude Desktop を再起動します

注：この方法では設定ファイルを手動で編集する必要があるため、注意して使用してください。変更を加える前に、必ず設定ファイルをバックアップしてください。

接続の確認

• 「今日の予定は何ですか？」のような、カレンダーに関する簡単な質問を Claude にします
• カレンダーの情報が返ってくれば、接続は正常に機能しています

Claude との接続に関するトラブルシューティング

Claude が MCP サーバーに接続できない場合：

1. Claude の応答を確認する： 通常、接続に問題がある場合は Claude が知らせてくれます

2. サーバー URL を確認する： /mcp パスを含む正しい URL を指定していることを確認します

3. サーバーログを確認する： MCP サーバーを実行しているコンソールにエラーメッセージがないか確認します

4. 両方のアプリケーションを再起動する： Claude Desktop と MCP サーバーの両方を再起動すると、接続の問題が解決することがあります

5. 認証状態を確認する： 接続を使用する前に、Google の認証が正常に完了していることを確認します

6. Anthropic サポートに問い合わせる： Claude が外部サーバーに接続できないというメッセージが表示された場合、お使いの Claude Desktop のバージョンで MCP 機能を利用できるかどうか、Anthropic サポートに問い合わせる必要がある場合があります

Claude コマンドのリファレンス

接続後は、Claude にさまざまなカレンダー操作を依頼できます。

# View your schedule
What events do I have today?
What's on my calendar for next week?
Show me my meetings for tomorrow afternoon.

# Create events
Schedule a team meeting next Monday at 10 AM for 1 hour.
Add a doctor's appointment on Friday at 2 PM.
Create a recurring weekly check-in every Wednesday at 9 AM.

# Modify events
Reschedule my 3 PM meeting to 4 PM.
Move tomorrow's lunch meeting to Thursday.
Cancel my dentist appointment.

# Find available times
When am I free tomorrow for a 2-hour meeting?
Do I have any conflicts next Tuesday morning?
Find me an open 30-minute slot this week for a quick call.

テスト

# Run tests
npm test
# or
yarn test

API エンドポイント

サーバーは次の MCP エンドポイントを公開しています。

認証

• GET /mcp/auth/url - Google OAuth2 認証 URL を取得します
• POST /mcp/auth/callback - 認証後の OAuth2 コールバックを処理します
• POST /auth/direct - Google アカウントで直接認証します（直接認証方法を使用する場合）

カレンダー

• GET /mcp/calendars - 利用可能なカレンダーの一覧を取得します

イベント

• GET /mcp/events - 特定のカレンダーからイベントを取得します
• GET /mcp/events/upcoming - すべてのカレンダーから今後のイベントを取得します
• POST /mcp/events/create - 新しいカレンダーイベントを作成します
• PUT /mcp/events/update - 既存のカレンダーイベントを更新します
• DELETE /mcp/events/delete - カレンダーイベントを削除します
• GET /mcp/events/detail - 特定のイベントの詳細を取得します

サーバー情報

• GET /mcp/info - サーバー情報と利用可能なエンドポイントを取得します
• GET /health - ヘルスチェックエンドポイント

Claude Desktop での使用例

Claude Desktop でこの MCP サーバーを使用する例を紹介します。

1. 今後のイベントを取得する

Claude, what are my upcoming calendar events for the next week?

Claude は MCP サーバーに問い合わせ、今後のイベントの一覧を返します。

2. 新しいイベントを作成する

Claude, please schedule a meeting with John Doe about the project proposal for tomorrow at 2:00 PM, lasting for 1 hour.

Claude は依頼に基づいて新しいカレンダーイベントを作成します。

3. スケジュールの重複を見つける

Claude, do I have any scheduling conflicts next Monday between 10 AM and 3 PM?

Claude は指定した期間のカレンダーを確認し、既存のイベントがあれば知らせます。

4. イベントの日時を変更する

Claude, I need to reschedule my doctor's appointment on Thursday to Friday at the same time.

Claude がイベントを見つけ、新しい日時に更新します。

5. 定期的な会議を設定する

Claude, please create a weekly team standup meeting every Monday at 9:00 AM starting next week.

Claude が定期的なカレンダーイベントを作成します。

6. 空き時間を探す

Claude, when am I free for a 2-hour meeting with the design team this week?

Claude がカレンダーを分析し、空いている時間帯を提案します。

Docker によるデプロイ

このプロジェクトには、簡単にデプロイできるよう Docker の設定が含まれています。

# Build and run with Docker Compose
docker-compose up -d

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

• この MCP サーバーは認証トークンをファイルにローカル保存します。これらのファイルを安全に保管し、バージョン管理にコミットしないようにしてください。
• 本番環境では、より安全なトークン保存方法の実装を検討してください。
• 本番モードでは、セキュアな通信のため、サーバーはデフォルトで HTTPS を使用します。
• トークンの有効期限が切れた際の更新は自動的に処理されます。

トラブルシューティング

認証に関する問題

認証に関する問題が発生した場合：

1. .env ファイルで認証情報が正しく設定されていることを確認してください
2. リダイレクト URI が Google Cloud Console で設定したものと完全に一致することを確認してください（Cloud OAuth の場合）
3. Google Cloud プロジェクトで Google Calendar API が有効になっていることを確認してください（Cloud OAuth の場合）
4. トークンファイルを削除して、もう一度認証を行ってください

接続に関する問題

Claude Desktop が MCP サーバーに接続できない場合：

1. サーバーが起動しており、指定された URL からアクセスできることを確認してください
2. ファイアウォールの設定を確認し、ポートが開いていることを確認してください
3. サーバーのポートが、Claude Desktop の接続先ポートと一致していることを確認してください

カレンダーへのアクセスに関する問題

カレンダーやイベントにアクセスできない場合：

1. 認証フロー中に必要な権限を許可したことを確認してください
2. Google アカウントが、表示しようとしているカレンダーへのアクセス権を持っていることを確認してください
3. 使用されているカレンダー ID が正しいことを確認してください

貢献

貢献を歓迎します。お気軽にプルリクエストを送信してください。

ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細については LICENSE ファイルをご覧ください。