npm package: @procedure-tech/mcp-google
Description: MCP server for multi-Google-account access (Gmail, Calendar, Drive) [BETA - Google OAuth approval pending, by-invite access]
Author: Anthropic
Latest version: 0.3.3

# MCP Google Multi-Account Server

> **Beta Notice:** This package uses OAuth credentials that are pending Google's verification review. During this period, access is by-invite only — you must be added as a test user in the Google Cloud Console to complete OAuth. Alternatively, you can [bring your own OAuth credentials](#advanced-bring-your-own-oauth-credentials). Once Google approval is granted, this notice will be removed.

An MCP (Model Context Protocol) server for accessing multiple Google accounts from Claude Code, Claude Desktop, or any MCP-compatible client. Supports Gmail, Google Drive, and Google Calendar.

**Just talk to Claude naturally:**
```
"Check my email"
"Find messages from my boss this week"
"Write a reply thanking them for the update"
"Send it"
```

No special commands to memorize - Claude understands what you want.

## Quick Start

No Google Cloud setup needed -- just install and connect your Google account:

**Claude Code CLI:**
```bash
claude mcp add proGoogleMCP -- npx -y @procedure-tech/mcp-google
```

**Claude Desktop** -- add to your `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "proGoogleMCP": {
      "command": "npx",
      "args": ["-y", "@procedure-tech/mcp-google"]
    }
  }
}
```

Then use the `google_add_account` tool to connect your Google account. That's it!

## Features

- **Zero config**: Works out of the box -- no Google Cloud project setup required
- **Natural language**: Just describe what you want - "find my unread emails", "draft a reply"
- **Multi-account support**: Connect work, personal, and other accounts - search across all of them
- **Full Gmail access**: Search, read, compose, send, and organize emails
- **Google Drive**: Search, upload, download, and share files
- **Google Calendar**: View, create, update, and manage events
- **Attachments**: Download and send file attachments
- **Inbox management**: Labels, archive, trash, read/unread status
- **Filters & vacation**: Create email filters and configure vacation responders
- **AI productivity**: Thread summaries, smart reply suggestions, action item extraction
- **Safety first**: All sends require confirmation - Claude shows you the draft before sending
- **Privacy focused**: All credentials stored locally on your machine

## Installation

### From npm

```bash
npx -y @procedure-tech/mcp-google
```

### Local Development

```bash
git clone https://github.com/bkbaheti/google-multi-account-mcp.git
cd google-multi-account-mcp
pnpm install
pnpm build
```

## Prerequisites

1. **Node.js 20+** - Required runtime
2. **Claude Code or Claude Desktop** - MCP client to connect to this server

That's it! OAuth credentials are built in. See [Advanced: Bring Your Own OAuth Credentials](#advanced-bring-your-own-oauth-credentials) if you want to use your own GCP project.

## Configuration

### Configure Claude Code (CLI)

```bash
# Add to current project only (default)
claude mcp add proGoogleMCP -- npx -y @procedure-tech/mcp-google

# Add globally (available in all projects)
claude mcp add -s user proGoogleMCP -- npx -y @procedure-tech/mcp-google

# With passphrase for token encryption
claude mcp add -s user proGoogleMCP -e MCP_GOOGLE_PASSPHRASE=optional-passphrase -- npx -y @procedure-tech/mcp-google
```

To verify or remove:
```bash
claude mcp list                # List configured servers
claude mcp remove proGoogleMCP # Remove this server
```

### Configure Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "proGoogleMCP": {
      "command": "npx",
      "args": ["-y", "@procedure-tech/mcp-google"]
    }
  }
}
```

### Advanced: Bring Your Own OAuth Credentials

If you prefer to use your own GCP project, you can override the built-in defaults:

- **Environment variables**: Set `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET`
- **Config file**: Add `oauth.clientId` and `oauth.clientSecret` to `~/.config/mcp-google/config.json`

Priority: environment variables > config file > built-in defaults.

<details>
<summary>Click for full GCP setup instructions</summary>

#### Step 1: Create a Google Cloud Project

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project (or select an existing one)

#### Step 2: Enable APIs

1. Go to **APIs & Services** > **Library**
2. Enable the APIs you need: **Gmail API**, **Google Drive API**, **Google Calendar API**

#### Step 3: Configure OAuth Consent Screen

1. Go to **APIs & Services** > **OAuth consent screen**
2. Select **External** user type (unless you have Google Workspace)
3. Fill in the required fields (app name, support email, developer contact)
4. Add the scopes you need (e.g., Gmail, Drive, Calendar)
5. Add your Google email as a test user

#### Step 4: Create OAuth 2.0 Client ID

1. Go to **APIs & Services** > **Credentials**
2. Click **Create Credentials** > **OAuth client ID**
3. Select **Desktop app** as the application type
4. Copy the **Client ID** and **Client Secret**

#### Step 5: Add Redirect URI

1. Under **Authorized redirect URIs**, add: `http://localhost:8089/callback`

#### Step 6: Configure

Set via environment variables:
```bash
export GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GOOGLE_CLIENT_SECRET="your-client-secret"
```

Or add to `~/.config/mcp-google/config.json`:
```json
{
  "version": 1,
  "oauth": {
    "clientId": "your-client-id.apps.googleusercontent.com",
    "clientSecret": "your-client-secret"
  }
}
```

</details>

## Usage

### Getting Started

1. Start Claude Code (or restart if already running to pick up config changes)

2. Verify the server is connected and check the version:
   ```
   "What version of the Google MCP server is running?"
   ```
   Claude will show the version, git commit, and build date.

3. Add a Google account:
   ```
   "Add my Gmail account"
   ```
   Claude will:
   - Ask which permissions you need (readonly, compose, full, etc.)
   - Show you an authorization URL to open in your browser
   - After you complete OAuth in the browser, Claude will confirm the account was added

4. Start using your email:
   ```
   "Find my unread emails"
   "Search for emails from john@example.com"
   "Draft a reply to the last email"
   ```

**Note:** These examples are natural language - Claude understands your intent and uses the appropriate MCP tools automatically. You don't need to know the tool names.

### Example Conversations

Here are some real-world examples of how to interact with Claude using this MCP server:

#### Reading and Searching Email

```
You: "Check my email for anything from Amazon in the last week"
Claude: [Searches and returns matching emails with subjects, dates, and snippets]

You: "Show me the full email about my order"
Claude: [Fetches the complete message with body content]

You: "What attachments are in that email?"
Claude: [Lists any attachments with filenames and sizes]
```

#### Composing and Sending

```
You: "Write an email to sarah@example.com thanking her for the meeting"
Claude: I'll draft that email for you.
       [Creates draft]
       Here's the draft:
       To: sarah@example.com
       Subject: Thank you for the meeting
       ...
       Would you like me to send it, or make any changes?

You: "Looks good, send it"
Claude: [Sends the email with confirmation]
```

#### Managing Your Inbox

```
You: "Archive all emails from newsletters@example.com"
Claude: [Archives matching messages]

You: "Create a label called 'Urgent' with a red color"
Claude: [Creates the label]

You: "Mark the last 5 unread emails as read"
Claude: [Updates the messages]
```

#### Multi-Account Workflows

```
You: "Add my work Gmail account"
Claude: Which permissions would you like?
        - readonly: Read and search only
        - compose: Also send emails (recommended)
        - full: Also manage labels, archive, trash
        ...

You: "Compose, please"
Claude: [Opens OAuth flow for work account]

You: "Label my work account as 'work' and my personal as 'personal'"
Claude: [Sets labels on both accounts]

You: "Search for 'project update' across all my accounts"
Claude: [Searches both accounts and shows combined results]
```

#### AI-Powered Productivity

```
You: "Summarize this email thread"
Claude: [Analyzes the thread and provides]:
        - Main topic: Q3 budget review
        - Participants: Finance team (5 people)
        - Key decisions: Budget approved with 10% increase
        - Action items: Submit receipts by Friday

You: "What action items do I have from my unread emails?"
Claude: [Scans unread messages and extracts tasks with deadlines]

You: "Suggest a reply to the last email"
Claude: Based on the context, here are 3 options:
        1. Brief: "Thanks, I'll review and get back to you."
        2. Detailed: [longer response addressing all points]
        ...
        Which would you like me to draft?
```

#### Setting Up Automation

```
You: "Create a filter to auto-archive emails from noreply@example.com"
Claude: I'll create that filter. This will automatically archive
        all future emails from that sender. Confirm?

You: "Yes"
Claude: [Creates the filter]

You: "Set up my vacation responder - I'm out Dec 20-27"
Claude: What message would you like to send?

You: "Just say I'm on holiday and will respond when I return"
Claude: [Configures vacation responder with dates]
```

### Scope Tiers

When adding an account, Claude will ask which permissions you need:

| Tier | What You Can Do | Best For |
|------|-----------------|----------|
| `mail_readonly` | Read and search emails | Checking email, research |
| `mail_compose` | + Create drafts and send | Daily email use (recommended) |
| `mail_full` | + Labels, archive, trash | Inbox organization |
| `mail_settings` | + Filters, vacation responder | Email automation |
| `drive_readonly` | Browse and download files | Reading documents |
| `drive_full` | + Upload, share, organize | File management |
| `calendar_readonly` | View events and calendars | Checking schedule |
| `calendar_full` | + Create, update, delete events | Schedule management |
| `all` | Everything above | Full control |

**How it works:**
- `readonly` → `compose` → `full` builds on each other
- `settings` is separate (for filters/vacation only)
- You can combine them: "I want inbox management AND filters" → `full` + `settings`

**Examples:**
```
You: "Add my Gmail account"
Claude: Which permissions would you like?
        [Shows options]

You: "I just want to read emails"
Claude: [Adds with readonly scope]

You: "Actually, I need to send emails too"
Claude: You'll need to remove and re-add with compose permissions.
        Want me to do that?
```

## Available Tools

You don't need to memorize tool names - just describe what you want. Here's what's available:

### Account Management

| Just Say... | What Happens |
|-------------|--------------|
| "Show my Google accounts" | Lists all connected accounts |
| "Add my Gmail account" | Starts OAuth flow to add account |
| "Remove my work account" | Disconnects account and revokes tokens |
| "Label this account as 'personal'" | Tags account for easy reference |

### Reading Email (readonly scope)

| Just Say... | What Happens |
|-------------|--------------|
| "Find emails from john@example.com" | Searches with Gmail query syntax |
| "Show me unread emails from this week" | Returns matching messages |
| "Get the full email about the project" | Fetches complete message content |
| "Show me that entire conversation" | Gets thread with all messages |
| "What attachments are in this email?" | Lists files with names and sizes |
| "Download the PDF attachment" | Retrieves the file data |

**Gmail search tips:** Use Gmail's search syntax for powerful queries:
- `from:someone@example.com` - From specific sender
- `subject:meeting` - Subject contains word
- `is:unread` - Unread messages only
- `has:attachment` - Messages with attachments
- `newer_than:7d` - Last 7 days
- `label:important` - Has specific label

### Composing Email (compose scope)

| Just Say... | What Happens |
|-------------|--------------|
| "Write an email to sarah@example.com" | Creates a draft for review |
| "Draft a reply to the last email" | Creates reply with proper threading |
| "Attach report.pdf to this draft" | Adds attachment to draft |
| "Update the draft - change the subject" | Modifies existing draft |
| "Show me my draft before sending" | Previews the draft |
| "Delete that draft" | Removes the draft |
| "Send the email" | Sends after confirmation |

**Safety feature:** All emails go through a draft-first workflow. Claude will always show you the draft and ask for confirmation before sending.

### Inbox Management (full scope)

| Just Say... | What Happens |
|-------------|--------------|
| "Show my labels" | Lists all Gmail labels |
| "Create a 'Projects' label in blue" | Creates label with color |
| "Rename 'Old' label to 'Archive'" | Updates label properties |
| "Delete the 'Temp' label" | Removes label (keeps messages) |
| "Add the 'Important' label to this email" | Applies label to message |
| "Label these 50 emails as 'Done'" | Bulk label operation |
| "Mark this as read" | Changes read status |
| "Archive this email" | Removes from inbox |
| "Delete this email" | Moves to trash |
| "Restore from trash" | Recovers deleted message |

### Filters & Vacation (settings scope)

| Just Say... | What Happens |
|-------------|--------------|
| "Show my email filters" | Lists automatic rules |
| "Create a filter for newsletters" | Sets up auto-processing |
| "Delete the filter for old@example.com" | Removes automation rule |
| "Check my vacation settings" | Shows auto-reply config |
| "Turn on vacation responder" | Enables auto-reply |
| "I'm back - disable vacation reply" | Turns off auto-reply |

### AI Productivity Prompts

These prompts guide Claude through complex workflows:

| Just Say... | What Happens |
|-------------|--------------|
| "Help me compose an email" | Guided drafting with preview and confirmation |
| "Help me reply to this thread" | Proper threading, tone matching |
| "Review my pending drafts" | Shows drafts, offers send/edit/delete |
| "Summarize this email thread" | Extracts key points, decisions, action items |
| "Suggest replies for this email" | Offers brief/standard/detailed options |
| "What action items do I have?" | Scans emails for tasks and deadlines |
| "Help me organize my inbox" | Suggests labels for uncategorized emails |

### Technical Reference

<details>
<summary>Click to see exact tool names (for advanced users)</summary>

**Account Management:**
- `google_version`, `google_list_accounts`, `google_add_account`, `google_check_pending_auth`, `google_remove_account`, `google_set_account_labels`

**Gmail Reading:**
- `gmail_search_messages`, `gmail_get_message`, `gmail_get_messages_batch`, `gmail_get_thread`, `gmail_list_attachments`, `gmail_get_attachment`

**Gmail Composing:**
- `gmail_create_draft`, `gmail_create_draft_with_attachment`, `gmail_update_draft`, `gmail_get_draft`, `gmail_delete_draft`, `gmail_send_draft`, `gmail_reply_in_thread`

**Inbox Management:**
- `gmail_list_labels`, `gmail_create_label`, `gmail_update_label`, `gmail_delete_label`, `gmail_modify_labels`, `gmail_batch_modify_labels`, `gmail_mark_read_unread`, `gmail_archive`, `gmail_trash`, `gmail_untrash`

**Settings:**
- `gmail_list_filters`, `gmail_create_filter`, `gmail_delete_filter`, `gmail_get_vacation`, `gmail_set_vacation`

**Google Drive:**
- `drive_search_files`, `drive_list_files`, `drive_get_file`, `drive_get_file_content`, `drive_upload_file`, `drive_create_folder`, `drive_move_file`, `drive_copy_file`, `drive_rename_file`, `drive_trash_file`, `drive_share_file`, `drive_update_permissions`

**Google Calendar:**
- `calendar_list_calendars`, `calendar_list_events`, `calendar_get_event`, `calendar_search_events`, `calendar_freebusy`, `calendar_create_event`, `calendar_update_event`, `calendar_delete_event`, `calendar_rsvp`, `calendar_move_event`

**MCP Prompts:**
- `compose-email`, `reply-to-email`, `review-drafts`, `summarize-thread`, `smart-reply`, `extract-action-items`, `categorize-emails`

**MCP Resources:**
- `accounts://list` - List connected accounts
- `cache://stats` - Cache statistics

</details>

## Environment Variables

| Variable | Description |
|----------|-------------|
| `MCP_GOOGLE_CONFIG_PATH` | Override default config file location |
| `MCP_GOOGLE_PASSPHRASE` | Passphrase for encrypted token storage (fallback when keychain unavailable) |
| `MCP_GOOGLE_LOG_LEVEL` | Log level: `debug`, `info`, `warn`, `error` |

## Troubleshooting

### "No refresh token received"

This can happen if you've previously authorized the app. To fix:
1. Go to [Google Account Permissions](https://myaccount.google.com/permissions)
2. Find and remove your MCP app
3. Say "Add my Gmail account" again

### OAuth URL not showing up

When adding an account, the OAuth authorization URL should appear in:
- **Claude Code**: Look for a warning-level log message with the URL
- **Claude Desktop**: Check the MCP server logs
- **Terminal stderr**: The URL is also written to stderr with a visible banner

If you don't see the URL:
1. Check your MCP client's log output or notification area
2. The URL is also logged to stderr - check terminal output if running manually
3. The OAuth flow times out after 5 minutes if not completed

### Port 8089 already in use

The OAuth callback server uses port 8089. If it's in use:
- Wait for the previous OAuth flow to complete
- Kill any process using the port: `lsof -ti:8089 | xargs kill`

### Keychain access issues (Linux/headless)

If the OS keychain is unavailable, set `MCP_GOOGLE_PASSPHRASE`:
```json
{
  "env": {
    "MCP_GOOGLE_PASSPHRASE": "your-secure-passphrase"
  }
}
```

Tokens will be encrypted with AES-256-GCM using this passphrase.

### "Scope insufficient" errors

You're trying to do something that requires more permissions than the account has.

```
You: "Archive this email"
Claude: This account only has readonly permissions. You need 'full' scope
        to archive emails. Would you like me to remove and re-add the
        account with higher permissions?
```

**Fix:** Say "Remove my account and add it back with full permissions"

### MCP server not connecting

1. Verify the path in your settings is correct and absolute
2. Ensure you've run `pnpm build` to compile TypeScript
3. Check that `dist/cli.js` exists
4. Try running manually: `node /path/to/dist/cli.js`

### Common Questions

**Q: Can I use multiple Google accounts?**
Yes! Just say "Add another Gmail account" and repeat the OAuth flow. You can label them ("Label my work account as 'work'") and search across all of them.

**Q: Will Claude send emails without asking?**
No. All sends require explicit confirmation. Claude will always show you the draft first and ask "Would you like me to send this?"

**Q: What happens if I accidentally delete an email?**
Emails go to Trash first and stay there for 30 days. Say "Show my trash" or "Restore that email from trash" to recover it.

**Q: Can Claude read my emails when I'm not using it?**
No. The MCP server only runs when Claude Code/Desktop is active, and only accesses emails when you ask it to.

## Development

```bash
# Install dependencies
pnpm install

# Build TypeScript
pnpm build

# Watch mode for development
pnpm dev

# Run tests
pnpm test

# Lint and format
pnpm lint:fix
pnpm format
```

## Security Notes

- **Zero-config OAuth**: Ships with built-in OAuth credentials (Desktop app type, same pattern as gcloud CLI). You can override with your own credentials if preferred.
- **Local storage**: All tokens are stored locally on your machine
- **Keychain preferred**: Uses OS keychain when available, falls back to encrypted file
- **Draft-first**: All sends require creating a draft first, then explicit confirmation
- **Account isolation**: Each account's tokens, cache, and rate limits are isolated

## License

MIT