gws-mcp

アクセス範囲と操作権限を厳しく絞った、Google Workspace MCP サーバーです。

LLM の誤操作による意図しない変更・削除・情報流出を防ぐための制限をコード側で強制します。

• 外部依存は Google 公式ライブラリのみです。サードパーティ製フレームワークは使いません。

対応サービスと操作範囲

※1 対象は「自分が所有者」かつ「共有ドライブに属していない（driveId がない）」ファイルだけです。どちらかを満たさないファイルへの書き込みは拒否します。 ※2 作成・更新できるのは自分のメインカレンダー（primary）だけです。更新は自分が主催者の予定に限ります。

Related MCP server: Google Drive MCP Server

セキュリティ設計

書き込みガード

Drive・スプレッドシート・ドキュメント・スライドの書き込み系ツールは、実行前に Drive API（files.get）で対象ファイルの情報を取得し、次のいずれかに当てはまれば API を呼ばずにエラーを返します。

• driveId がある（共有ドライブ内のファイル）

• ownedByMe が true でない（他人が所有するファイル）

• ゴミ箱に入っている

• ショートカットである（リンク先が共有ドライブのファイルかどうかを ID から判別できないため）

Drive のフォルダ作成・ファイル作成・コピーでは、作成先の親フォルダに同じ判定をかけます（既定の作成先はマイドライブ直下）。スプレッドシート・ドキュメント・スライドの新規作成は常にマイドライブ直下に作られ、作成後にできたファイルを同じ条件で確認します。ファイル ID は形式をチェックしてから使います。

カレンダーは Drive のファイルではないため、予定を取得して自分が主催者かを判定します（※2）。

OAuth スコープではマイドライブと共有ドライブを区別できないため、この制限はスコープではなくコード（gws_mcp/guard.py）で強制しています。

さらに Drive API の書き込み呼び出し（作成・更新・名前変更）には supportsAllDrives を付けません。付けなければ共有ドライブのファイルは API 側で「見つからない」扱いになるため、ガードとは別の二重の防御になります（共有ドライブのファイルを読むために必要なコピーだけは例外で、コピー先はガードで判定します）。

ツールとして公開しない操作

• ファイルの削除、ゴミ箱への移動、ゴミ箱を空にする

• 共有設定（permissions）の変更

• ファイルの移動（親フォルダの付け替え）

• 共有ドライブの作成・変更

• カレンダーの予定の削除、カレンダー自体の作成・削除・共有設定

• Gmail の送信・下書き作成・ラベル変更などの書き込み全般

• 任意の API を直接呼べる汎用ツール

その他の安全策

• スプレッドシート: 書き込みは既定で RAW（数式として解釈しない）です。IMPORTDATA などの数式でデータが外部に送られるのを防ぎます。数式を入れたいときだけ USER_ENTERED を明示します。

• カレンダー: 参加者がいる予定の作成・更新では、招待・通知メールを送るか（send_updates）の指定を必須にしており、指定がなければ実行しません。LLM には送るかをユーザーに確認してから指定するよう指示しています。書き込み先は自分のメインカレンダーに固定しており、共有カレンダーは編集権限があっても変更しません。

• トークン: 権限 0600 で保存します（ディレクトリは 0700）。サーバー実行中にブラウザ認証を始めることはありません。

• ログ: 標準エラー出力だけに出します（stdout は MCP 通信専用）。

OAuth スコープ

必要なもの

• Python 3.10 以上

• Google Workspace アカウント

• Google Cloud プロジェクト（OAuth クライアント作成用）

セットアップ

以下の手順はスキル(/setup)で対話的に進められます

1. Google Cloud の準備

1. Google Cloud Console でプロジェクトを作ります。

2. 「API とサービス」→「ライブラリ」で次の API を有効にします。

   • Google Drive API

   • Gmail API

   • Google Calendar API

   • Google Sheets API

   • Google Docs API

   • Google Slides API

3. 「Google Auth Platform」で OAuth 同意画面を設定し、「対象」でユーザーの種類に「内部」を選びます（組織利用が前提。個人利用で「外部」かつ「テスト中」にすると、トークンが 7 日で失効します）。

4. 「認証情報」→「認証情報を作成」→「OAuth クライアント ID」で、種類に デスクトップアプリ を選びます。

5. JSON をダウンロードし、~/.config/gws-mcp/credentials.json として保存します。

mkdir -p ~/.config/gws-mcp && chmod 700 ~/.config/gws-mcp
mv ~/Downloads/client_secret_*.json ~/.config/gws-mcp/credentials.json
chmod 600 ~/.config/gws-mcp/credentials.json

保存場所は環境変数 GWS_MCP_CONFIG_DIR で変更できます。

2. インストール

cd /path/to/gws-mcp
python3 -m venv .venv
.venv/bin/pip install -r requirements.lock

requirements.lock は、推移的な依存まで動作確認済みのバージョンで固定したものです。直接の依存（Google 公式4パッケージ）は requirements.txt で管理し、更新したときは .venv/bin/pip freeze > requirements.lock で作り直します。

3. 初回認証

.venv/bin/python scripts/authorize.py

ブラウザが開くので、Google アカウントでログインして権限を許可します。トークンは ~/.config/gws-mcp/token.json に保存されます。スコープを変えたときやトークンが無効になったときも、このコマンドを実行し直してください。

4. MCP クライアントへの登録

/path/to/gws-mcp は実際のパスに置き換えてください。config/ に設定例があります（Claude Code のプロジェクト設定 .mcp.json 用: claude-code.mcp.example.json、VS Code 用: vscode.mcp.example.json）。

Claude Code

claude mcp add --scope user gws -e PYTHONPATH=/path/to/gws-mcp -- /path/to/gws-mcp/.venv/bin/python -m gws_mcp

（--scope user でどのプロジェクトからも使えるようにします。PYTHONPATH はリポジトリ外から起動しても gws_mcp を読み込めるようにするためです）

VS Code（.vscode/mcp.json）

{
  "servers": {
    "gws": {
      "type": "stdio",
      "command": "/path/to/gws-mcp/.venv/bin/python",
      "args": ["-m", "gws_mcp"],
      "env": { "PYTHONPATH": "/path/to/gws-mcp" }
    }
  }
}

ツール一覧

Drive

Gmail（読み取りのみ）

カレンダー

スプレッドシート

ドキュメント

スライド

ディレクトリ構成

gws-mcp/
├── gws_mcp/
│   ├── server.py      # JSON-RPC 2.0 stdio サーバー（MCP プロトコル処理）
│   ├── schema.py      # ツール入力の検証
│   ├── auth.py        # OAuth 資格情報の読み込み・更新
│   ├── guard.py       # 書き込みガード（マイドライブ判定）
│   └── tools/         # サービスごとのツール実装（drive / gmail / calendar / sheets / docs / slides）
├── scripts/
│   └── authorize.py   # 初回 OAuth 認証
├── tests/             # unittest（Google API はモック）
├── config/            # 各 MCP クライアント用の設定例
├── .claude/           # Claude Code 用の skill（/setup・/check-updates など）と、資格情報へのアクセスを防ぐフック・設定
├── requirements.txt   # 直接の依存
└── requirements.lock  # 推移的な依存まで固定したもの（インストールに使う）

テスト

標準ライブラリの unittest だけで動きます（Google API はモックするので認証は不要です）。

.venv/bin/python -m unittest discover tests

メンテナンス

• 書き込みガード: 安全性を支える中心部分です。書き込みツールを追加するときは、Tool に guard=（判定の種類は tools/__init__.py）を宣言し、tests のガードのテスト対象一覧にも追加してください。どちらかが抜けていると、登録時のエラーかテストの失敗になります。書き込み用の API 呼び出しには supportsAllDrives を付けないでください。

• 旧方式のプロトコル対応: Claude Code と VS Code の両方が新方式で動くことを確認できてから、削除を検討します。どちらの方式で接続したかは、標準エラー出力のログ（initialize: か server/discover: か）で分かります。

• 入力検証: schema.py が対応している JSON Schema のキーワードは一部だけです。ツールの引数に新しい種類の制約が必要になったら、先に schema.py を拡張してください。

• 依存の更新: テストを実行し、requirements.lock を作り直したうえで、実際の環境で主要なツールを動かして確認してください。テストは Google API をモックしているため、API 側の変更は検出できません。

確認方法(/check-updates スキル)

定期的な更新確認は、Claude Code の /check-updates skill（.claude/skills/check-updates/SKILL.md）で行えます。

注意事項

• credentials.json と token.json は絶対にコミットしないでください（.gitignore で除外済み）。

• drive スコープはファイル全体への読み書き権限です。実際の書き込み制限はガードのコードに依存するので、ガードを変更するときはテストも更新してください。

• トークンを取り消すには、Google アカウントのサードパーティ接続 からアプリへのアクセスを削除し、token.json を消します。

ライセンス

MIT License