Skip to main content
Glama

Gmail second account MCP server

Version Python Node OAuth

Read and write one Gmail mailbox from Claude.ai and Claude Code. Claude.ai's own Gmail connector handles a single account, so this exists for the second one: run an instance per mailbox and each connector reaches exactly the address it was given.

WARNING

Using this server with a paid AI service costs money. Tool definitions and results are billed as input tokens, and an agent can call tools repeatedly on its own. You are responsible for every charge, so set spending limits with your provider. The author accepts no liability for any costs. SeeDISCLAIMER.md.

One mailbox per instance

Which account an instance serves comes from GMAIL_CREDENTIALS_DIR, and nothing else is reachable from that process. That separation is the point rather than a limitation: a draft cannot land in the wrong mailbox when the server only ever holds one set of credentials.

Related MCP server: Gmail MCP Local Server

Tools

Reading

Tool

What you get

gmail_profile

Which mailbox this instance serves, and its counts

gmail_search

Search with Gmail's own query syntax

gmail_get_message

One message, with its body

gmail_get_thread

A whole conversation, oldest first

gmail_list_attachments

Filenames, types and sizes on a message

gmail_list_labels

Every label with its id

gmail_list_drafts / gmail_get_draft

Drafts waiting in the mailbox

Writing

Tool

What it does

gmail_create_draft

Write a draft, optionally threaded as a reply

gmail_update_draft

Replace a draft's contents

gmail_delete_draft

Discard a draft

gmail_modify_labels

Add or remove labels on a message

gmail_archive

Take a message out of the inbox

gmail_mark_read

Mark read or unread

gmail_trash / gmail_untrash

Move to trash and back

gmail_create_label / gmail_delete_label

Manage labels

gmail_send_draft

Send an existing draft

gmail_send_message

Compose and send in one step

The two send tools are marked destructive and say so in their descriptions: they reach other people and cannot be undone. The safe shape is gmail_create_draft, read it, then gmail_send_draft once a person has approved the text.

Searching

gmail_search takes the same operators as the Gmail search box:

is:unread from:client.com
subject:invoice has:attachment newer_than:7d
label:important -in:trash

It returns headers and a snippet per message rather than bodies, so a wide search stays small. Follow up with gmail_get_message or gmail_get_thread.

How it fits together

Claude.ai / Claude Code
        |  HTTPS
   Cloudflare Tunnel, or any proxy that gives you HTTPS
        |
   nginx  127.0.0.1:8461
        |
   auth-server.js  :8462    handles the login and the tokens
        |
   gmail-mcp  :8460         the server itself, local only
        |
   gmail.googleapis.com

The MCP has no login of its own and refuses to listen on anything but the local machine, so everything reaching it has already passed the login.

Setup

You need a Google Cloud OAuth client with the Gmail API enabled, and a refresh token for the mailbox. The credentials directory holds two files:

credentials.json        {"refresh_token": "..."}
gcp-oauth.keys.json     the downloaded OAuth client

gmail.modify is the scope to grant. It covers reading, labelling, drafting and sending; drop to gmail.readonly plus gmail.compose if you would rather the credentials themselves could not send.

git clone https://github.com/rollecode/gmail-second-account-mcp.git
cd gmail-second-account-mcp
uv venv && uv pip install -e .
npm install --omit=dev

CONFIG_DIR=~/.config/gmail-mcp node set-password.js 'your-password-here'
openssl rand -hex 32 > ~/.config/gmail-mcp/token
chmod 600 ~/.config/gmail-mcp/token

Fill in YOUR_USER, the hostname and the credentials directory in systemd/*.service and nginx/gmail-mcp.conf, then:

sudo cp systemd/*.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now gmail-mcp gmail-mcp-auth

sudo cp nginx/gmail-mcp.conf /etc/nginx/sites-enabled/gmail-mcp
sudo nginx -t && sudo systemctl reload nginx

Point a tunnel or an HTTPS proxy at 127.0.0.1:8461. OAuth needs HTTPS.

Check from outside: discovery returns metadata, and /mcp without a token must return 401.

curl https://your-host/.well-known/oauth-authorization-server
curl -o /dev/null -w '%{http_code}\n' -X POST https://your-host/mcp

Connecting

Claude.ai: Settings, Connectors, Add custom connector, https://your-host/mcp, client ID and secret blank.

Claude Code:

claude mcp add --transport http gmail https://your-host/mcp \
  --header "Authorization: Bearer $(cat ~/.config/gmail-mcp/token)" --scope user

Locally over stdio, with no server at all:

GMAIL_CREDENTIALS_DIR=/path/to/creds claude mcp add gmail -- /path/to/.venv/bin/gmail-mcp

Settings

Variable

What it is for

GMAIL_CREDENTIALS_DIR

Directory holding credentials.json and gcp-oauth.keys.json

GMAIL_ACCOUNT_LABEL

Name for the mailbox, shown in the server's instructions

MCP_PUBLIC_URL

Public address, used to advertise the icon

ISSUER

Public origin of the login server

PORT

Login server port, 8462 by default

UPSTREAM

MCP server URL, http://127.0.0.1:8460 by default

CONFIG_DIR

Where the password, token and OAuth database live

Access tokens are refreshed in memory as they expire; only the refresh token is read from disk.

Credits

The login layer comes from rollecode/obsidian-remote-mcp.

Available Tools

21 tools
get_result_pageA
Read-onlyIdempotent

Read more of a result that was too large to return in one piece.

Any tool whose answer is too large returns its first page with a paging block. Pass that block's result_id here. Nothing is fetched again: the stored result is paged, filtered and narrowed.

Args: result_id: From the paging block of the earlier answer. offset: First item to return, usually the previous next_offset. limit: At most this many items. Fewer come back if they would not fit. fields: Only these keys of each item. Dots reach nested keys, such as "statistics.sizeOnDisk". The paging.fields list shows what exists. match: Keep only items whose field contains this text, ignoring case, for example {"title": "alien", "year": "1979"}. path: Which list to page when the result holds several, as named in paging.lists. Defaults to the largest.

Inputs: result_id (required), path, limit, match, +2 more. Returns: result

gmail_archiveA
Idempotent

Archive a message by taking it out of the inbox. Nothing is deleted.

Args: message_id: Message to archive.

Inputs: message_id (required). Returns: result

gmail_create_draftA
Idempotent

Write a draft. It waits in the mailbox until a person sends it.

Passing reply_to_message_id threads the draft onto that message and sets the reply headers, so it appears in the conversation rather than as a new one.

Args: to: Recipient address, or several separated by commas. subject: Subject line. body: Plain text body. cc: Carbon copy addresses. bcc: Blind carbon copy addresses. reply_to_message_id: Message this replies to.

Inputs: to (required), body (required), subject (required), cc, +2 more. Returns: result

gmail_create_labelB
Idempotent

Create a label. Use Parent/Child to nest it.

Args: name: Label name.

Inputs: name (required). Returns: result

gmail_delete_draftB
DestructiveIdempotent

Discard a draft.

Args: draft_id: Draft to delete.

Inputs: draft_id (required). Returns: result

gmail_delete_labelA
DestructiveIdempotent

Delete a label. Messages keep their content but lose the label.

Args: label_id: Label id from gmail_list_labels.

Inputs: label_id (required). Returns: result

gmail_get_draftA
Read-onlyIdempotent

One draft in full, including its body.

Args: draft_id: Draft id from gmail_list_drafts.

Inputs: draft_id (required). Returns: result

gmail_get_messageA
Read-onlyIdempotent

One message in full, including its body text.

Args: message_id: Message id from gmail_search.

Inputs: message_id (required). Returns: result

gmail_get_threadA
Read-onlyIdempotent

A whole conversation, oldest message first.

Read this before replying: a thread's later messages often change what the first one asked for.

Args: thread_id: Thread id from gmail_search or gmail_get_message.

Inputs: thread_id (required). Returns: result

gmail_list_attachmentsA
Read-onlyIdempotent

What is attached to a message: filenames, types and sizes.

Args: message_id: Message id from gmail_search.

Inputs: message_id (required). Returns: result

gmail_list_draftsC
Read-onlyIdempotent

Drafts waiting in the mailbox.

Args: limit: Maximum drafts to return, up to 100.

Inputs: limit. Returns: result

gmail_list_labelsA
Read-onlyIdempotent

Every label, with its id. Label ids are what the filing tools take.

Inputs: no named parameters. Returns: result

gmail_mark_readA
Idempotent

Mark a message read, or unread with read=false.

Args: message_id: Message to mark. read: True marks it read, False marks it unread.

Inputs: message_id (required), read. Returns: result

gmail_modify_labelsA
Idempotent

Add or remove labels on a message.

The system labels are INBOX, UNREAD, STARRED, IMPORTANT, SPAM and TRASH. Removing INBOX archives a message; removing UNREAD marks it read.

Args: message_id: Message to file. add: Label ids to add. remove: Label ids to remove.

Inputs: message_id (required), add, remove. Returns: result

gmail_profileA
Read-onlyIdempotent

Which mailbox this server serves, and how much is in it.

Worth calling first when more than one Gmail connector is set up, so a reply goes to the right account.

Inputs: no named parameters. Returns: result

gmail_send_draftA
DestructiveIdempotent

Send an existing draft. This reaches other people and cannot be undone.

Show the draft and get an explicit yes before calling this. Sending is not a step in a plan; it is the thing the person decides.

Args: draft_id: Draft to send.

Inputs: draft_id (required). Returns: result

gmail_send_messageA
DestructiveIdempotent

Compose and send in one step. This reaches other people immediately and cannot be undone.

Prefer gmail_create_draft, then gmail_send_draft once the text has been read and approved. Use this only when told to send outright.

Args: to: Recipient address, or several separated by commas. subject: Subject line. body: Plain text body. cc: Carbon copy addresses. bcc: Blind carbon copy addresses.

Inputs: to (required), body (required), subject (required), cc, +1 more. Returns: result

gmail_trashB
DestructiveIdempotent

Move a message to the trash, where Gmail keeps it for 30 days.

Args: message_id: Message to trash.

Inputs: message_id (required). Returns: result

gmail_untrashA
Idempotent

Take a message back out of the trash.

Args: message_id: Message to restore.

Inputs: message_id (required). Returns: result

gmail_update_draftA
Idempotent

Replace a draft's contents. Gmail rewrites the whole message, so pass every field, not only the changed one.

Args: draft_id: Draft to replace. to: Recipient address. subject: Subject line. body: Plain text body. cc: Carbon copy addresses. bcc: Blind carbon copy addresses.

Inputs: to (required), body (required), subject (required), draft_id (required), +2 more. Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 21 tools

    Disambiguation4/5

    Most tools target distinct actions (search, get, draft, label, send). However, gmail_archive and gmail_mark_read are convenience wrappers that overlap with gmail_modify_labels, though the descriptions clearly steer usage. No severe confusion, but a few boundaries could be tighter.

    Naming Consistency4/5

    Nearly all tools use a consistent gmail_ prefix with snake_case verb_noun structure. The lone exception is get_result_page, which breaks the prefix pattern and is a generic paging tool. This minor deviation keeps it from a perfect score.

    Tool Count4/5

    21 tools is on the higher side but reasonable for full Gmail functionality including search, reading, labels, drafts, and sending. Each tool has a clear purpose, though a few convenience wrappers could be folded into gmail_modify_labels. Still well within acceptable scope for a complex domain.

    Completeness3/5

    Core email workflows are covered (search, read, draft, send, label, archive, trash). However, notable gaps exist: no way to download attachment content, and gmail_send_message and drafts lack attachment parameters, which will cause failures for common attachment tasks. Thread-level label operations are also missing.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables reading, sending, searching, and managing Gmail through Claude using the official Google Gmail API.
      3
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables Gmail integration with Claude Code for reading, sending, searching emails, and managing labels through natural language.
      ISC