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. 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:

claude mcp add proGoogleMCP -- npx -y @procedure-tech/mcp-google

Claude Desktop -- add to your claude_desktop_config.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, preview, download to disk, upload from disk, 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

npx -y @procedure-tech/mcp-google

Local Development

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 if you want to use your own GCP project.

Configuration

Configure Claude Code (CLI)

# 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:

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):

{
  "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
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: Redirect URI — nothing to configure

Desktop app clients have no "Authorized redirect URIs" field, and none is needed. The server binds an OS-assigned port on 127.0.0.1 for each OAuth flow and Google accepts any loopback port for this client type.

If you created a Web application client instead, the loopback flow will not work — Web clients require every redirect URI to be registered exactly, and the port is not fixed. Create a Desktop app client.

#### Step 6: Configure

Set via environment variables:

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:

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

1. 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.

1. Add a Google account:

   "Add my Gmail account"

Claude will:

• Ask which capabilities you need — pick a preset (read-only, inbox-assistant, scheduler) or choose individual capabilities like mail:read or drive:appfiles
• Show you an authorization URL to open in your browser
• After you complete OAuth in the browser, Claude will confirm the account was added

1. Start using your email:

   "Find my unread emails"
   "Search for emails from [email protected]"
   "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 [email protected] thanking her for the meeting"
Claude: I'll draft that email for you.
       [Creates draft]
       Here's the draft:
       To: [email protected]
       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 [email protected]"
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 capabilities would you like?
        - read-only: Read mail, Drive, and calendar (preset)
        - inbox-assistant: Read, send, and organize mail (preset)
        - Or pick individual capabilities: mail:read, mail:compose, mail:modify, ...

You: "inbox-assistant, 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 [email protected]"
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]

Capabilities

When adding an account, Claude will ask which capabilities you need. Each capability is an independent, per-service grant — pick only what you actually need:

<!-- BEGIN GENERATED: capabilities -->

<!-- END GENERATED: capabilities -->

How it works:

• Capabilities are independent per service — grant any combination you like.
• The one exception: mail:modify already includes everything mail:read and mail:compose do, so you never need to grant those alongside it.
• drive:read and drive:appfiles are deliberately independent, not tiers of each other — drive:read sees everything in the Drive read-only, drive:appfiles can create/edit/delete but only within files this app touched. Grant both if you want broad read plus app-created writes.
• For the common cases, start from a preset instead of picking capabilities one by one:
• read-only → mail:read, drive:read, calendar:read
• inbox-assistant → mail:modify (read, send, and organize mail)
• scheduler → calendar:read + calendar:write
• Presets are just a shortcut — they expand to the same capabilities above before anything is stored, and you can still add more on top.

Examples:

You: "Add my Gmail account"
Claude: Which capabilities would you like? Pick a preset (read-only,
        inbox-assistant, scheduler) or choose individually.
        [Shows options]

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

You: "Actually, I need to send emails too"
Claude: I'll reauth this account to add mail:compose — your account ID,
        alias, and labels all stay the same. 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

Reading Email (mail:read)

Gmail search tips: Use Gmail's search syntax for powerful queries:

• from:[email protected] - 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 (mail:compose)

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 (mail:modify)

Filters & Vacation (mail:settings)

AI Productivity Prompts

These prompts guide Claude through complex workflows:

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_reauth_account, google_remove_account, google_set_account_labels, google_set_account_alias, google_set_account_description

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_list_shared_drives, drive_search_files, drive_list_files, drive_get_file, drive_get_file_content, drive_get_full_file_content, drive_download_file, drive_upload_file, drive_create_folder, drive_move_file, drive_copy_file, drive_rename_file, drive_trash_file, drive_share_file, drive_update_permissions — all tools work with Shared Drives (Team Drives)

Google Calendar:

• calendar_list_calendars, calendar_list_colors, 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
• calendar_list_calendars reports accessRole and a derived canEdit per calendar, so a shared calendar you can only read is distinguishable from one you can write to.
• calendar_create_event and calendar_update_event take addMeet: true to generate a Google Meet link. meetingCode attaches an existing conference instead (a code or a https://meet.google.com/... URL) and needs confirm: true, because a reused conference keeps its access bound to the original event's guest list. calendar_update_event also takes removeConferencing: true.
• Event colours. Every read tool returns the event's colorId. calendar_create_event and calendar_update_event take colorId as either an id ("11") or a Calendar colour name ("Tomato", "Basil", …); calendar_update_event takes resetColor: true to put an event back on its calendar's colour. calendar_list_colors shows the palette. A colour-only update notifies no attendees and needs no confirm — a guest's copy is coloured by their own settings, so there is nothing for them to see — which is what makes recolouring a run of existing events practical.

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

Troubleshooting

"No refresh token received"

This can happen if you've previously authorized the app. To fix:

1. Go to Google Account 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

OAuth callback port

The callback server binds an OS-assigned port on 127.0.0.1 for each flow, so there is no fixed port to free up and concurrent flows do not collide. Earlier versions used a fixed port 8089; if you have a firewall rule pinned to that port, it is no longer used.

Keychain access issues (Linux/headless)

If the OS keychain is unavailable, set MCP_GOOGLE_PASSPHRASE:

{
  "env": {
    "MCP_GOOGLE_PASSPHRASE": "your-secure-passphrase"
  }
}

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

"Capability insufficient" errors

You're trying to do something that requires a capability the account doesn't have.

You: "Archive this email"
Claude: This account only has mail:read. Archiving needs mail:modify.
        Want me to reauth this account to add it? Your account ID,
        alias, and labels all stay the same.

Fix: Say "Reauth this account and add mail:modify" — no need to remove and re-add; google_reauth_account preserves the account ID, alias, description, and labels while updating its capabilities.

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

# 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