Google Workspace MCP

🚀 なぜ google-workspace-mcp なのか

• 1つのサーバーで、すべてのアカウント。 各ツール呼び出しが account スラグ（例：work、personal）を渡します。サーバーはそのアカウントのOAuthトークンを透過的に読み込み・更新します — 切り替えも、サーバーの分離も不要です。
• プロジェクト単位のアクセス制御。 アカウントは実行時に設定され、コードに埋め込まれることはありません。各プロジェクトの .mcp.json がサブセットにスコープを絞るため、個人プロジェクトが業務アカウントを目にすることは一切ありません。
• 自分のOAuthクライアントを使用。 無料のGoogle Cloud OAuthクライアントを自分で用意するため、アクセス権を自分で所有し、デフォルトの claude.ai コネクタではできない機能（下書きの削除など）を含むツール全体を利用できます。通信が他者のインフラを経由することはありません。
• シークレットはツリーの外に。 OAuthクライアントとアカウントごとのリフレッシュトークンは ~/.config/google-workspace-mcp/（パーミッション 0600）に保存され、コードの隣に置かれることはありません。
• 4つのサービスにまたがる38のツール — 詳細は下記の ツール一覧 を参照してください。

📚 目次

• インストール
• セットアップ
• プロジェクト単位のアクセス制御
• ツール
• 設定とストレージ
• スコープ
• 信頼とセキュリティ
• リポジトリ構成
• 開発
• コントリビューション
• ライセンス

📦 インストール

/plugin コマンドはClaude Codeの内部で実行します — プロンプトに入力してください。

# 1) マシンごとに一度、マーケットプレイスを登録
/plugin marketplace add rajool/google-workspace-mcp

# 2) プラグインをインストール
/plugin install google-workspace-mcp@google-workspace-mcp

これにより /google-workspace-setup コマンドが利用可能になります。このコマンドは セットアップ の内容をすべて案内します — 前提条件の確認、OAuthクライアントの作成、アカウントの定義、各アカウントの適切なブラウザでの認証、そしてサーバーのプロジェクトへの接続まで。

{
  "extraKnownMarketplaces": {
    "google-workspace-mcp": {
      "source": { "source": "github", "repo": "rajool/google-workspace-mcp" }
    }
  },
  "enabledPlugins": {
    "google-workspace-mcp@google-workspace-mcp": true
  }
}

⚙️ セットアップ

PATH上に uv が必要です。/google-workspace-setup コマンドがこれらの手順を自動化しますが、以下は手動での手順です。

1. 自分のGoogle Cloud OAuthクライアントを作成する

各ユーザーが自身のクライアントを作成します（無料）：

1. Google Cloud Console にアクセスし、プロジェクトを作成（または既存のものを選択）します。

2. APIs & Services → Enabled APIs & services → + Enable APIs — Gmail、Google Calendar、Google Drive、Google Tasks のAPIを有効化します。

3. APIs & Services → OAuth consent screen — ユーザータイプは External を選択。必須項目を入力します。テストユーザー に、接続予定のすべてのGoogleアカウントを追加します（アプリを Testing のままにしておいて問題ありません）。

4. APIs & Services → Credentials → + Create credentials → OAuth client ID → Application type: Desktop app。JSONをダウンロードします。

5. そのJSONを以下として保存します：

   ~/.config/google-workspace-mcp/credentials.json
   

2. サーバーバイナリをインストールする

プロジェクトの .mcp.json が名前で起動できるようにするため：

# GitHubから：
uv tool install git+https://github.com/rajool/google-workspace-mcp

# …またはローカルクローンから：
uv tool install .

これにより2つのコマンドがインストールされます：google-workspace-mcp（サーバー）と google-workspace-authorize（OAuthヘルパー）。

3. アカウントを定義する

各アカウントに短いスラグを付けます。方法は2つ：

a) レジストリファイル（推奨）— ~/.config/google-workspace-mcp/accounts.json（テンプレート：）：

{
  "accounts": {
    "work":     { "email": "you@company.com", "name": "Your Name" },
    "personal": { "email": "you@gmail.com",   "name": "Your Name" }
  }
}

name は送信メールの From: ヘッダーに表示される表示名です（空のアドレスで送信したい場合は "" に設定）。

b) またはプロジェクトごとにインラインで GWM_ACCOUNTS 環境変数を経由（ステップ5 を参照）— 共有レジストリファイルを使いたくない場合に便利です。

4. 各アカウントを認証する

これによりGoogleの同意URLが出力されます — その アカウントでサインインしているブラウザで開き、許可 をクリックしてください：

# accounts.json に登録済みのアカウント — スラグだけでOK：
google-workspace-authorize work

# または、新規アカウントをインラインで登録（accounts.json に追加される）：
google-workspace-authorize personal you@gmail.com "Your Name"

「Google hasn't verified this app」という警告をクリックして進みます（自分のアプリです）→ Continue → Select all → Continue。リフレッシュトークンは ~/.config/google-workspace-mcp/tokens/<slug>.json に書き込まれます。

5. プロジェクトに接続する

プロジェクトのルートに .mcp.json を追加します。GWM_ACCOUNTS がこのプロジェクトで使用できるアカウントを決定します：

{
  "mcpServers": {
    "google-workspace": {
      "command": "google-workspace-mcp",
      "env": { "GWM_ACCOUNTS": "work,personal" }
    }
  }
}

• GWM_ACCOUNTS はレジストリからのスラグのカンマ区切りリスト、または（レジストリを省略した場合）インラインJSONマップ（{"work":{"email":"…","name":"…"}}）にできます。
• GWM_ACCOUNTS を省略すると、レジストリ内のすべてのアカウントが公開されます。

Claude Codeを再起動する（またはMCPを再接続する）と反映されます。その後、Claudeにアカウント一覧を尋ねて確認してください。

🔒 プロジェクト単位のアクセス制御

GWM_ACCOUNTS の狙いは分離です：プロジェクトは、リストにないアカウントとしては文字通り動作できません — サーバーがそのスラグを拒否します。トークンは中央に保存されます（一度認証すればOK）が、各プロジェクトの .mcp.json が自身のスライスを選択します：

🧰 ツール

すべての呼び出しには account スラグが必要です。accounts_list は設定済みのアカウントと、有効なトークンを持つアカウントを表示します。

📧 Gmail

📅 Calendar

📁 Drive

✅ Tasks

🗂️ 設定とストレージ

すべては設定ホーム以下に配置されます — $GWM_HOME、なければ $XDG_CONFIG_HOME/google-workspace-mcp、それもなければ ~/.config/google-workspace-mcp/：

トークンファイルは 0600 で書き込まれます。

🔑 スコープ

意図的に広めに設定しています — これらはあなた自身のアカウントであり、狭いスコープではツールを追加するたびに再認証が必要になるためです：

• https://mail.google.com/
• https://www.googleapis.com/auth/calendar
• https://www.googleapis.com/auth/drive
• https://www.googleapis.com/auth/tasks

スコープを追加する場合（v0.3.0でTasksに対して行ったように）、各アカウントで google-workspace-authorize <slug> を再実行する必要があります。

🛡️ 信頼とセキュリティ

• ローカル専用。 サーバーはClaude Codeとstdioで通信し、GoogleのAPIとのみ通信します。唯一開くリスナーは、google-workspace-authorize 中の一時的な 127.0.0.1 リダイレクトで、同意が完了するとすぐに閉じられます。
• あなたのクライアント、あなたのトークン。 OAuthクライアントとトークンはあなたのマシン上に留まり、このリポジトリの外にあります。credentials.json や tokens/ をコミットしないでください（同梱の が両方を拒否します）。
• ユーザー間で何も共有されません。 各チームメイトは自身のOAuthクライアントを実行し、自身のアカウントを認証します。
• 設定ディレクトリをシークレットストアとして扱う。 トークンはメール/カレンダー/ドライブ/タスクへの広範なアクセスを許可します — ~/.config/google-workspace-mcp/ は ~/.ssh/ と同じくらいの注意を払うべきです。
• メール送信やファイル共有が可能なMCPサーバーは、有効化する前にレビューに値します — 全体は にある約1,300行のPythonです。脆弱性の報告は SECURITY.md を参照してください。

📁 リポジトリ構成

google-workspace-mcp/
├── .claude-plugin/
│   ├── plugin.json                  # the plugin manifest
│   └── marketplace.json             # single-repo marketplace (source: "./")
├── commands/
│   └── google-workspace-setup.md    # /google-workspace-setup — guided setup
├── src/google_workspace_mcp/
│   ├── server.py                    # the MCP server — all 38 tools
│   ├── auth.py                      # token load/refresh + Google service builders
│   ├── accounts.py                  # runtime account registry + GWM_ACCOUNTS scoping
│   └── authorize.py                 # standalone OAuth consent flow (CLI)
├── accounts.example.json            # template for ~/.config/google-workspace-mcp/accounts.json
├── pyproject.toml                   # uv/hatchling package — the two console scripts
└── .github/workflows/ci.yml         # lint, import smoke test, manifest validation

🛠️ 開発

git clone https://github.com/rajool/google-workspace-mcp
cd google-workspace-mcp
uv sync                                   # create .venv with locked deps
claude --plugin-dir .                     # load the plugin without installing

# Quality gates (CI runs the same — see .github/workflows/ci.yml)
uvx ruff check .                          # lint
uv run python -m py_compile src/google_workspace_mcp/*.py
uv run python -c "from google_workspace_mcp import server"   # import smoke test
claude plugin validate . --strict         # validate plugin + marketplace manifests

ユーザー向けの変更は 、、src/google_workspace_mcp/__init__.py の version を更新し、 にエントリを追加します — インストール済みのプロジェクトは /plugin marketplace update で反映されます。

🤝 コントリビューション

コントリビューションを歓迎します。このリポジトリは 公開・汎用・英語のみ です — 個人のメールアドレス、実際のアカウントスラグ、ホームパス、シークレットは含めないでください。開発セットアップとチェックについては CONTRIBUTING.md、コミュニティの期待事項については CODE_OF_CONDUCT.md を参照してください。

📄 ライセンス

MIT © Ali Rajool. yar と boote と同じツールキットファミリーの一部です。