Google Calendar MCP Server

# Google Calendar MCP Server

Google Calendar APIを使用したMCP（Model Context Protocol）サーバーです。FastMCPフレームワークを使用してGoogleカレンダーの操作機能を提供します。

## 機能

- **カレンダー一覧取得**: 利用可能なGoogleカレンダーの一覧を取得
- **イベント取得**: 指定したカレンダーからイベントを取得
- **イベント作成**: 新しいカレンダーイベントを作成
- **イベント削除**: カレンダーイベントを削除

## 要件

- Python 3.12以上
- Google Cloud Platformプロジェクト
- Google Calendar API有効化
- OAuth2認証情報

## インストール

1. リポジトリをクローン
```bash
git clone <repository-url>
cd google-calendar-mcp
```

2. 依存関係をインストール
```bash
pip install -e .
```

またはuvを使用する場合:
```bash
uv sync
```

## 設定

### 1. Google Cloud Platform設定

1. [Google Cloud Console](https://console.cloud.google.com/)でプロジェクトを作成
2. Google Calendar APIを有効化
3. OAuth2認証情報を作成
4. 必要な環境変数を設定

### 2. 環境変数設定

以下の環境変数を設定してください:

```bash
export GOOGLE_CLIENT_ID="your_client_id"
export GOOGLE_CLIENT_SECRET="your_client_secret"
export GOOGLE_PROJECT_ID="your_project_id"
export GOOGLE_REFRESH_TOKEN="your_refresh_token"
```

または`.env`ファイルに設定:

```env
GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
GOOGLE_PROJECT_ID=your_project_id
GOOGLE_REFRESH_TOKEN=your_refresh_token
```

### 3. OAuth2認証情報の取得

1. Google Cloud ConsoleでOAuth2認証情報を作成
2. 認証フローを実行してリフレッシュトークンを取得
3. 取得した値を環境変数に設定

## 使用方法

### MCPサーバーとして実行

```bash
python main.py
```

### 直接実行

```bash
python -m src.google_calendar_mcp
```

## API仕様

### list_calendars()

利用可能なGoogleカレンダーの一覧を取得します。

**引数**: なし

**戻り値**:
- `success` (bool): 処理が成功したかどうか
- `calendars` (List[Dict]): カレンダー情報のリスト
- `count` (int): カレンダー数
- `error` (str): エラーメッセージ（失敗時）

### get_events()

指定したカレンダーからイベントを取得します。

**引数**:
- `calendar_id` (str): カレンダーID（デフォルト: 'primary'）
- `time_min` (str): 開始時刻（ISO形式、デフォルト: 現在時刻）
- `time_max` (str): 終了時刻（ISO形式、デフォルト: 7日後）
- `max_results` (int): 最大取得件数（デフォルト: 10）

**戻り値**:
- `success` (bool): 処理が成功したかどうか
- `events` (List[Dict]): イベント情報のリスト
- `count` (int): イベント数
- `error` (str): エラーメッセージ（失敗時）

### create_event()

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

**引数**:
- `summary` (str): イベントタイトル（必須）
- `start_time` (str): 開始時刻（ISO形式、必須）
- `end_time` (str): 終了時刻（ISO形式、必須）
- `description` (str): イベントの説明（デフォルト: ''）
- `location` (str): 場所（デフォルト: ''）
- `calendar_id` (str): カレンダーID（デフォルト: 'primary'）
- `attendees` (List[str]): 参加者メールアドレスのリスト（デフォルト: None）

**戻り値**:
- `success` (bool): 処理が成功したかどうか
- `event_id` (str): 作成されたイベントのID
- `event_link` (str): イベントのGoogleカレンダーリンク
- `message` (str): 成功メッセージ
- `error` (str): エラーメッセージ（失敗時）

### delete_event()

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

**引数**:
- `event_id` (str): 削除するイベントのID（必須）
- `calendar_id` (str): カレンダーID（デフォルト: 'primary'）

**戻り値**:
- `success` (bool): 処理が成功したかどうか
- `message` (str): 成功メッセージ
- `error` (str): エラーメッセージ（失敗時）

## テスト

### モックモードでのテスト実行

```bash
python run_tests.py --mode mock
```

### 実際のAPIを使用したテスト実行

```bash
python run_tests.py --mode real_api
```

### カバレッジレポート付きテスト実行

```bash
python run_tests.py --mode mock --coverage
```

### 特定のテスト実行

```bash
python run_tests.py --mode mock --test test_calendar_tools.py::TestListCalendars
```

## プロジェクト構造

```
google-calendar-mcp/
├── src/
│   ├── __init__.py
│   ├── google_calendar_mcp.py    # MCPサーバーのメインエントリーポイント
│   ├── auth/
│   │   ├── __init__.py
│   │   └── google_auth.py        # Google認証処理
│   └── tools/
│       ├── __init__.py
│       └── calendar_tools.py     # カレンダー操作機能
├── tests/
│   ├── __init__.py
│   └── test_calendar_tools.py    # テストコード
├── main.py                       # アプリケーションエントリーポイント
├── run_tests.py                  # テスト実行スクリプト
├── pyproject.toml                # プロジェクト設定
├── pytest.ini                   # pytest設定
└── README.md                     # このファイル
```

## 依存関係

- `fastmcp`: MCPサーバーフレームワーク
- `google-api-python-client`: Google APIクライアント
- `google-auth-httplib2`: Google認証ライブラリ
- `google-auth-oauthlib`: OAuth2認証ライブラリ
- `python-dotenv`: 環境変数管理
- `pytest`: テストフレームワーク
- `pytest-mock`: モックテストライブラリ

## ライセンス

このプロジェクトのライセンスについては、LICENSEファイルを参照してください。

## 貢献

プルリクエストやイシューの報告を歓迎します。

## トラブルシューティング

### 認証エラー

- 環境変数が正しく設定されているか確認
- OAuth2認証情報が有効か確認
- Google Calendar APIが有効化されているか確認

### 権限エラー

- 必要なスコープが設定されているか確認
- カレンダーへのアクセス権限があるか確認

### テストエラー

- 環境変数`USE_REAL_API`の設定を確認
- 必要な依存関係がインストールされているか確認