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. 依存関係のインストール

cd company-mcp
pnpm install

2. Google Cloud プロジェクトの設定

詳細は docs/setup/oauth.md または docs/setup/service-account.md を参照。

簡易手順（OAuth）:

Google Cloud Console でプロジェクト作成
APIs & Services > Enable APIs で以下を有効化:
- Gmail API
- Google Drive API
- Google Sheets API
- Google Docs API
- Google Calendar API
APIs & Services > Credentials で OAuth 2.0 Client ID を作成（Desktop App）
クレデンシャルJSONをダウンロードし .secrets/credentials.json に配置

3. 環境変数の設定

cd apps/mcp-server-google
cp .env.example .env
# .env を編集

4. OAuth認証（初回のみ）

# 読み取り専用
pnpm auth:oauth

# 送信機能も有効化する場合
GMAIL_SEND_ENABLED=true pnpm auth:oauth

5. ビルド

pnpm build

Claude Code から使う

設定ファイルの追加

~/.claude.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 に記録されます:

{"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"

pnpm auth:oauth

で認証してください。

"Token has expired"

refresh_token がない場合は再認証が必要です:

rm .secrets/token.json
pnpm auth:oauth

"Folder not in allowlist"

DRIVE_ALLOWLIST_FOLDERS にフォルダIDを追加してください。

Rate Limit (429)

Google API のレート制限に達しました。しばらく待ってから再試行してください。

開発

ビルド

pnpm build

型チェック

pnpm typecheck

Lint

pnpm lint

テスト

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 を参照してください。

ライセンス

MIT

company-mcp