# Company MCP Server - Google Workspace Integration
社内共通の MCP (Model Context Protocol) サーバー。Google Workspace (Gmail / Drive / Sheets / Docs / Calendar) をClaude Codeから操作できます。
## 概要
このリポジトリは以下を提供します：
- **MCP Server** (`apps/mcp-server-google`): Google Workspace連携のMCPサーバー
- **Core Library** (`packages/core`): 共通ユーティリティ（logger, config, validation, auth）
- **Skills** (`packages/skills`): Claude Codeでの活用方法・プロンプト集
- **Documentation** (`docs/`): セットアップ手順、セキュリティガイド、トラブルシューティング
## できること
### Gmail
| ツール | 説明 | 要有効化 |
|--------|------|----------|
| `gmail_search_messages` | メール検索 | - |
| `gmail_get_message` | メール詳細取得 | - |
| `gmail_list_labels` | ラベル一覧取得 | - |
| `gmail_modify_labels` | ラベル変更 | `GMAIL_MODIFY_LABELS_ENABLED` |
| `gmail_send_message` | メール送信 | `GMAIL_SEND_ENABLED` |
| `gmail_reply_message` | メール返信 | `GMAIL_SEND_ENABLED` |
| `gmail_delete_message` | メール削除 | `GMAIL_DELETE_ENABLED` |
| `gmail_create_draft` | 下書き作成 | `GMAIL_SEND_ENABLED` |
| `gmail_get_attachment` | 添付ファイル取得 | - |
### Drive
| ツール | 説明 | 要有効化 |
|--------|------|----------|
| `drive_search_files` | ファイル検索 | - |
| `drive_get_file` | ファイル情報取得 | - |
| `drive_create_folder` | フォルダ作成 | `DRIVE_MODIFY_ENABLED` |
| `drive_set_permission` | 共有設定 | `DRIVE_MODIFY_ENABLED` |
| `drive_copy_file` | ファイルコピー | `DRIVE_MODIFY_ENABLED` |
| `drive_upload_file` | ファイルアップロード | `DRIVE_MODIFY_ENABLED` |
| `drive_download_file` | ファイルダウンロード | - |
| `drive_delete_file` | ファイル削除 | `DRIVE_DELETE_ENABLED` |
| `drive_move_file` | ファイル移動 | `DRIVE_MODIFY_ENABLED` |
### Sheets
| ツール | 説明 |
|--------|------|
| `sheets_create_spreadsheet` | スプレッドシート作成 |
| `sheets_get_values` | セル値取得 |
| `sheets_update_values` | セル値更新 |
| `sheets_append_values` | 行追加 |
| `sheets_batch_get_values` | 一括取得 |
| `sheets_batch_update_values` | 一括更新 |
| `sheets_add_sheet` | シート追加 |
| `sheets_delete_sheet` | シート削除 |
| `sheets_format_cells` | セル書式設定 |
### Docs
| ツール | 説明 |
|--------|------|
| `docs_create_document` | ドキュメント作成 |
| `docs_get_document` | ドキュメント取得 |
| `docs_insert_text` | テキスト挿入 |
| `docs_replace_text` | テキスト置換 |
| `docs_format_text` | テキスト書式設定 |
| `docs_insert_image` | 画像挿入 |
| `docs_batch_update` | 一括更新 |
### Calendar
| ツール | 説明 | 要有効化 |
|--------|------|----------|
| `calendar_list_events` | イベント一覧 | - |
| `calendar_create_event` | イベント作成（dry-run対応） | `CALENDAR_MODIFY_ENABLED` |
| `calendar_update_event` | イベント更新（dry-run対応） | `CALENDAR_MODIFY_ENABLED` |
| `calendar_delete_event` | イベント削除 | `CALENDAR_MODIFY_ENABLED` |
| `calendar_get_free_busy` | 空き時間検索 | - |
## クイックスタート
### 1. 依存関係のインストール
```bash
cd company-mcp
pnpm install
```
### 2. Google Cloud プロジェクトの設定
詳細は [docs/setup/oauth.md](docs/setup/oauth.md) または [docs/setup/service-account.md](docs/setup/service-account.md) を参照。
**簡易手順（OAuth）:**
1. [Google Cloud Console](https://console.cloud.google.com/) でプロジェクト作成
2. APIs & Services > Enable APIs で以下を有効化:
- Gmail API
- Google Drive API
- Google Sheets API
- Google Docs API
- Google Calendar API
3. APIs & Services > Credentials で OAuth 2.0 Client ID を作成（Desktop App）
4. クレデンシャルJSONをダウンロードし `.secrets/credentials.json` に配置
### 3. 環境変数の設定
```bash
cd apps/mcp-server-google
cp .env.example .env
# .env を編集
```
### 4. OAuth認証（初回のみ）
```bash
# 読み取り専用
pnpm auth:oauth
# 送信機能も有効化する場合
GMAIL_SEND_ENABLED=true pnpm auth:oauth
```
### 5. ビルド
```bash
pnpm build
```
## Claude Code から使う
### 設定ファイルの追加
`~/.claude.json` に追加:
```json
{
"mcpServers": {
"google": {
"command": "node",
"args": ["/path/to/company-mcp/apps/mcp-server-google/dist/index.js"],
"env": {
"AUTH_MODE": "oauth",
"OAUTH_TOKEN_PATH": "/path/to/company-mcp/.secrets/token.json",
"GMAIL_SEND_ENABLED": "true"
}
}
}
}
```
### 使用例
```
Claude: Gmail で未読メールを検索して
→ gmail_search_messages({"query": "is:unread", "maxResults": 10})
```
```
Claude: 今週のカレンダーイベントを教えて
→ calendar_list_events({
"timeMinISO": "2024-01-15T00:00:00Z",
"timeMaxISO": "2024-01-21T23:59:59Z"
})
```
```
Claude: kai@example.com に「会議の件」という件名でメールを送って
→ gmail_send_message({
"to": ["kai@example.com"],
"subject": "会議の件",
"body": "メール本文..."
})
```
## 安全設計
### デフォルトで無効な操作
以下の操作はデフォルトで**無効**です。`.env` で明示的に有効化してください:
| 操作 | 環境変数 | デフォルト |
|------|----------|-----------|
| Gmailの送信/返信/下書き | `GMAIL_SEND_ENABLED` | `false` |
| Gmailの削除 | `GMAIL_DELETE_ENABLED` | `false` |
| Gmailのラベル変更 | `GMAIL_MODIFY_LABELS_ENABLED` | `false` |
| Driveの変更操作 | `DRIVE_MODIFY_ENABLED` | `false` |
| Driveの削除 | `DRIVE_DELETE_ENABLED` | `false` |
| Calendarの変更操作 | `CALENDAR_MODIFY_ENABLED` | `false` |
### Dry-Run モード
Calendar の作成・更新は**デフォルトで dry-run モード**です。実際に作成するには `dryRun: false` を明示的に指定するか、`CALENDAR_DRY_RUN_DEFAULT=false` を設定してください。
### フォルダ制限
`DRIVE_ALLOWLIST_FOLDERS` で操作可能なフォルダIDを制限できます。Service Account 運用時は必ず設定してください。
### 日本語対応
メールの件名・本文は自動的にRFC 2047 / Base64エンコードされるため、日本語が正しく表示されます。
### 監査ログ
全ての操作は `logs/audit-YYYY-MM-DD.jsonl` に記録されます:
```json
{"timestamp":"2024-01-15T10:30:00.000Z","level":"info","tool":"gmail_search_messages","action":"search","args":{"query":"is:unread"},"result":"success","duration_ms":234}
```
## よくあるエラー
### "No OAuth token found"
```bash
pnpm auth:oauth
```
で認証してください。
### "Token has expired"
refresh_token がない場合は再認証が必要です:
```bash
rm .secrets/token.json
pnpm auth:oauth
```
### "Folder not in allowlist"
`DRIVE_ALLOWLIST_FOLDERS` にフォルダIDを追加してください。
### Rate Limit (429)
Google API のレート制限に達しました。しばらく待ってから再試行してください。
## 開発
### ビルド
```bash
pnpm build
```
### 型チェック
```bash
pnpm typecheck
```
### Lint
```bash
pnpm lint
```
### テスト
```bash
pnpm test
```
## ディレクトリ構成
```
company-mcp/
├── apps/
│ └── mcp-server-google/ # MCPサーバー本体
│ ├── src/
│ │ ├── auth/ # 認証モジュール
│ │ ├── tools/ # ツール実装
│ │ │ ├── gmail.ts
│ │ │ ├── drive.ts
│ │ │ ├── sheets.ts
│ │ │ ├── docs.ts
│ │ │ └── calendar.ts
│ │ └── index.ts # エントリーポイント
│ └── .env.example # 環境変数テンプレート
├── packages/
│ ├── core/ # 共通ライブラリ
│ │ └── src/
│ │ ├── config.ts # 設定管理
│ │ ├── logger.ts # ロガー
│ │ ├── validation.ts # バリデーションスキーマ
│ │ └── auth.ts # 認証ユーティリティ
│ └── skills/ # プロンプト・ワークフロー集
├── docs/
│ ├── setup/ # セットアップ手順
│ ├── security/ # セキュリティガイド
│ ├── workflows/ # ワークフロー例
│ └── troubleshooting/ # トラブルシューティング
├── scripts/ # ユーティリティスクリプト
└── .github/workflows/ # CI設定
```
## コントリビューション
[CONTRIBUTING.md](CONTRIBUTING.md) を参照してください。
## ライセンス
MIT
