Gmail & Calendar Multi-Account MCP Server

A local Model Context Protocol (MCP) server that connects multiple Gmail accounts and Google Calendars to Claude Desktop. Runs entirely on your machine — no cloud hosting required.

Features

• Multiple accounts — connect as many Gmail or Google Workspace accounts as you need

• Unified email search — search across all accounts simultaneously with Gmail's full query syntax

• Full read access — read individual messages and entire threads

• Send & draft — compose and send emails, or save drafts, from any account

• Label management — list labels, mark as read/unread, star messages

• Google Calendar — list calendars, browse upcoming events, search by keyword

• Google Docs — create, read, update, and delete documents

• Google Sheets — create, read, update, and delete spreadsheets, with cell formatting

• Google Forms — create, read, update, and delete forms, questions, and settings; read submitted responses

Related MCP server: Google Workspace MCP

Requirements

• macOS (tested on macOS 14+)

• Python 3.11+

• A Google Cloud project with the Gmail API, Calendar API, Docs API, Sheets API, and Forms API enabled (free)

• Claude Desktop

Installation

1. Clone the repository

git clone https://github.com/DiegoMaldonadoRosas/gmail-mcp.git
cd gmail-mcp

2. Run the setup script

bash setup.sh

This creates a virtual environment and installs all Python dependencies.

3. Configure your accounts

Copy the example config and fill in your accounts:

cp config.json.example config.json

Edit config.json:

{
  "accounts": {
    "personal": {
      "email": "you@gmail.com",
      "description": "Personal Gmail",
      "signature_html": "<div><br>--<br><strong>Your Name</strong><br>example.com</div>",
      "signature_image_path": "./signatures/personal.png"
    },
    "work": {
      "email": "you@company.com",
      "description": "Work account",
      "signature_image_path": "./signatures/work.png"
    }
  },
  "credentials_dir": "./credentials"
}

The account keys (personal, work) are the names you'll use when asking Claude to interact with a specific account.

Per-account signatures (optional)

Each account can have a signature applied automatically to every message it sends — you never pass signature info as a tool parameter. The signature is resolved from the first available source in this priority order (only one source is ever used per email):

1. Auto-fetched Gmail signature — the signature set in that account's own Gmail Settings (Settings → See all settings → Signature), read live via the Gmail Settings API. If a signature exists there, it's used and config.json is ignored. Nothing to configure.

2. signature_html (config.json) — used only if no Gmail signature is set. Appended to the HTML part of the email.

3. signature_image_path (config.json) — used only if neither of the above applies. The image is embedded inline at the bottom of the email (via Content-ID / <img src="cid:...">), so it appears as a signature image, not a file attachment. Path is relative to the project root or absolute.

4. No signature — if none of the above is set.

A plain-text body is always included as a fallback for clients that don't render HTML.

Re-authentication required: Auto-fetching needs the gmail.settings.basic scope, which was added to SCOPES. Accounts authenticated before this change must be re-authenticated once (python setup_auth.py) before the auto-fetched signature will work. Until then, the server silently falls back to the config.json sources.

4. Get Google OAuth credentials

1. Go to Google Cloud Console

2. Create a project and enable the Gmail API, Google Calendar API, Google Drive API, Google Docs API, Google Sheets API, and Google Forms API

3. Go to APIs & Services → Credentials → + Create Credentials → OAuth 2.0 Client ID

4. Choose Desktop app as the application type

5. Download the JSON file and save it as credentials/client_secret.json

6. Go to APIs & Services → OAuth consent screen → Test users and add every email address you configured in config.json

5. Authenticate your accounts

source .venv/bin/activate
python setup_auth.py

A browser window will open for each account. Sign in with the correct Google account. Tokens are saved locally and refreshed automatically — you only need to do this once per account.

Note: If you previously authenticated for Gmail only, you must re-run setup_auth.py after adding Calendar support so the tokens include the new Calendar permissions. The same applies after adding Google Docs, Sheets, or Forms support — re-run setup_auth.py once per account so tokens pick up the new documents/spreadsheets/forms.body/forms.responses.readonly scopes, or docs_*/sheets_*/forms_* calls will fail with a permission error.

6. Add the server to Claude Desktop

Open ~/Library/Application Support/Claude/claude_desktop_config.json and add:

{
  "mcpServers": {
    "gmail": {
      "command": "/absolute/path/to/gmail-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/gmail-mcp/server.py"]
    }
  }
}

Replace /absolute/path/to/gmail-mcp with the actual path where you cloned the repo.

7. Restart Claude Desktop

All tools will appear automatically.

Available Tools

Gmail

gmail_send / gmail_create_draft parameters

Google Calendar

Google Docs

docs_update parameters

At least one of append_text or find_text must be provided.

docs_format parameters

At least one style change (bold, italic, underline, strikethrough, font_size, font_family, foreground_color, and/or background_color) must be provided, and either find_text or start_index/end_index to target the range.

Google Sheets

Ranges use A1 notation, e.g. "Sheet1!A1:D10" or just "Sheet1" for the whole tab.

sheets_format parameters

At least one style change must be provided.

Google Forms

Known limitation: the Forms API cannot create FILE_UPLOAD questions at all (a hard Google API restriction, not something this server can work around). Submitted file-upload answers can still be read via forms_get_response/forms_list_responses (returned as Drive file IDs), just not created as a new question.

forms_add_question parameters

Usage Examples

Once connected, you can ask Claude things like:

Email:

• "Do I have any unread emails in my work account?"

• "Search for invoices received in the last month across all my accounts"

• "Read the last email from John in my personal account"

• "Draft a reply to the budget email in my work account"

• "Mark all emails from newsletter@example.com as read"

Calendar:

• "What meetings do I have this week in my work account?"

• "Search for events related to 'product launch' in my personal calendar"

• "List all my calendars in my work account"

• "What are the details of tomorrow's standup?"

Docs:

• "Create a Google Doc called 'Meeting Notes' in my work account"

• "Read the content of this doc: "

• "Append today's action items to the end of my project plan doc"

• "Replace all instances of 'Q1' with 'Q2' in that doc"

Adding a New Account

1. Add the account to config.json

2. Add the email as a Test User in Google Cloud Console (OAuth consent screen)

3. Run python setup_auth.py — it will only prompt for the new account

4. Restart Claude Desktop

Security

• OAuth tokens are stored locally in credentials/tokens/ and are excluded from version control via .gitignore

• config.json (which contains your email addresses) is also excluded from version control

• Nothing is sent to any third-party server — all communication is directly between your Mac and Google's APIs

• To revoke access at any time, visit myaccount.google.com/permissions

Project Structure

gmail-mcp/
├── server.py           # MCP server — exposes tools to Claude
├── auth.py             # OAuth2 token manager (per account)
├── gmail.py            # Gmail API wrapper
├── gcalendar.py        # Google Calendar API wrapper
├── gdrive.py           # Google Drive API wrapper
├── gdocs.py            # Google Docs API wrapper
├── config.py           # Configuration loader
├── setup_auth.py       # One-time authentication script
├── setup.sh            # First-time installer
├── requirements.txt    # Python dependencies
├── config.json.example # Account configuration template
└── .gitignore          # Excludes credentials and config.json

License

MIT