Skip to main content
Glama
gmail-multi-mcp

gmail-multi-mcp

gmail-multi-mcp

An open-source MCP server that connects any number of Gmail accounts to Claude (or any MCP client) in one place. Everything runs locally, and your tokens never leave your machine.

Tools

Tool

What it does

list_accounts

Lists the connected accounts, with alias and read-only status

search_emails

Runs a Gmail search query on one account or all of them at once

read_email / read_thread

Reads one message or a whole conversation as plain text, with a list of attachments

list_labels

Lists the labels for an account

list_send_as

Lists the addresses an account can send from (Gmail's "Send mail as")

send_email

Sends mail from a chosen account, including threaded replies. from_address picks one of the account's "Send mail as" addresses

create_draft

Saves a draft instead of sending

modify_labels

Marks mail read or unread, archives, stars, or adds and removes labels

trash_email

Moves a message to Trash (recoverable)

Every tool takes an account argument, which can be the full email address or an alias such as work.

Sender addresses: if an account has extra addresses under Gmail's Settings → Accounts → Send mail as, send_email and create_draft can send from any of them with from_address. Without it, a reply goes out from the address the original was sent to, and a new mail goes out from Gmail's default sender.

Related MCP server: gmail-mcp

1. Create a Google OAuth client (once)

  1. Open https://console.cloud.google.com/ and create a project.

  2. APIs & Services → Library → enable the Gmail API.

  3. APIs & Services → OAuth consent screen: choose External and fill in the app name and your email. Under Test users, add every Gmail address you want to connect.

  4. APIs & Services → Credentials → Create credentials → OAuth client ID → Desktop app. Download the JSON file.

  5. Save the file as ~/.config/gmail-multi-mcp/credentials.json.

Tip: while the app is in Testing status, Google expires refresh tokens after 7 days. For personal use you can click Publish app on the consent screen. It stays unverified, so you'll see an "unverified app" warning when you sign in, but the tokens stop expiring.

One OAuth client works for all your accounts.

2. Install

Install uv. It also installs Python for you:

curl -LsSf https://astral.sh/uv/install.sh | sh

Then install the server straight from GitHub:

uv tool install https://github.com/anitalklausen/gmail-multi-mcp/archive/refs/heads/main.zip

To install from a local clone instead, run uv tool install . in the project folder.

This puts gmail-multi-mcp in ~/.local/bin.

3. Connect accounts

Run this once per account. A browser opens where you choose the Google account:

gmail-multi-mcp add --alias private
gmail-multi-mcp add --alias work
gmail-multi-mcp add --alias shop --read-only
gmail-multi-mcp list

Remove an account with gmail-multi-mcp remove work. New accounts are picked up by the running server without a restart.

4. Add it to Claude

Claude Desktop: go to Settings → Developer → Edit Config and add the server to claude_desktop_config.json:

{
  "mcpServers": {
    "gmail": {
      "command": "/Users/YOUR_USERNAME/.local/bin/gmail-multi-mcp"
    }
  }
}

Use the absolute path, because Claude Desktop does not read your shell's PATH. Restart Claude Desktop afterwards.

Claude Code:

claude mcp add gmail --scope user -- ~/.local/bin/gmail-multi-mcp

Configuration

Environment variable

Effect

GMAIL_MCP_HOME

Config/token folder. The default is ~/.config/gmail-multi-mcp.

GMAIL_MCP_CREDENTIALS

Path to the OAuth client JSON

GMAIL_MCP_READ_ONLY=1

Hides every write tool (send, draft, labels, trash) for all accounts

Security

  • Tokens are stored in tokens/<email>.json with 600 permissions. Treat them like passwords.

  • The default scope is gmail.modify: read, send, and change labels, but never permanent deletion. Accounts added with --read-only get gmail.readonly.

  • The server tells the model to confirm with you before sending, and Claude also asks for approval on every tool call.

See also the privacy policy.

License

MIT

Available Tools

9 tools
create_draftB

Save an email as a draft in the given account (not sent).

Inputs: to (required), body (required), account (required), subject (required), +3 more.

list_accountsA

List all connected Gmail accounts with their alias and read-only status.

Inputs: no named parameters. Returns: result

list_labelsC

List labels (system and user-created) for an account.

Inputs: account (required). Returns: result

modify_labelsB

Add/remove labels by name or id. Examples: mark read = remove ['UNREAD']; archive = remove ['INBOX']; star = add ['STARRED'].

Inputs: account (required), message_id (required), add_labels, remove_labels.

read_emailB

Read one email in full (headers, plain-text body, attachment list).

Inputs: account (required), message_id (required), max_body_chars.

read_threadC

Read every message in a conversation thread, oldest first.

Inputs: account (required), thread_id (required), max_body_chars. Returns: result

search_emailsA

Search email using Gmail search syntax (e.g. 'is:unread from:bob newer_than:7d').

Args: query: Gmail search query. Empty returns the newest messages. account: Email or alias. Omit to search ALL connected accounts. max_results: Max messages per account (1-50).

Inputs: query, account, max_results.

send_emailA

Send an email from the given account. Confirm content with the user first.

Args: account: Sender account (email or alias). to: Comma-separated recipients. subject: Subject. May be empty when replying (uses 'Re: '). body: Plain-text body. reply_to_message_id: Message id to reply to; keeps the thread intact.

Inputs: to (required), body (required), account (required), subject (required), +3 more.

trash_emailB

Move a message to Trash (recoverable for 30 days).

Inputs: account (required), message_id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 9 tools

    Disambiguation4/5

    Each tool has a fairly distinct purpose: reading, searching, sending, drafting, trashing, and label management are all clearly separated. The only mild overlap is between modify_labels (which can apply TRASH/UNREAD labels) and trash_email, plus list_labels vs modify_labels, but descriptions make the intended use clear.

    Naming Consistency5/5

    All nine tools follow a strict verb_noun snake_case pattern (list_accounts, search_emails, read_email, read_thread, list_labels, modify_labels, trash_email, send_email, create_draft). No camelCase or vague verbs mixed in.

    Tool Count5/5

    Nine tools is a well-scoped surface for a multi-account Gmail server, covering the core mailbox operations without bloat. Every tool maps to a distinct mailbox workflow.

    Completeness4/5

    Core lifecycle is well covered: list/search/read/read thread, send, draft, trash, and label management across accounts. Minor gaps remain — no attachment download, no permanent delete (only trash), and no explicit forward or mark-spam/unspam tool, though these can be approximated with existing tools.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol (MCP) server that enables Claude Desktop to interact with Gmail through secure OAuth 2.0 authentication. Send emails, search messages, read emails, and manage multiple Gmail accounts directly from Claude Desktop.
      298 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Connects Gmail to Claude and other MCP clients so an assistant can search and read mail, send, reply-all with quoted history, forward, handle attachments and inline images, and manage drafts, labels, and threads. Runs as a remote server on your own Cloudflare Worker, serving several Google accounts simultaneously to desktop, browser, and phone clients while you retain the refresh tokens.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables Claude to search and read multiple Gmail or Google Workspace mail accounts at once through a local, read-only MCP server, with every result labeled by the account it came from. Tokens stay in the OS keychain, no server is run by the authors, and write actions such as sending, deleting, or archiving are not supported.
      12 npm
      1
      AGPL 3.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Connects several Gmail and Google Workspace accounts to MCP-capable AI apps so they can search, read, draft, send, reply, and label mail across one account or all of them at once. Runs locally on Windows with encrypted on-disk credentials, no delete tools, and approval-gated sending.
      MIT