Skip to main content
Glama
gmail-mcp-server

gmail-mcp-server

by m-ishit

gmail-mcp-server

A local MCP (Model Context Protocol) server that connects multiple Gmail accounts to Claude Desktop. Unlike Anthropic's built-in Gmail connector (which only supports one account), every tool call here takes an account parameter so Claude can work across several mailboxes in the same conversation.

Runs entirely on your own machine — no cloud hosting, no data leaves your computer except direct calls to the Gmail API over HTTPS.

Works on macOS and Windows.

Tools provided

  • list_accounts — list connected Gmail accounts

  • search_threads, get_thread, get_message — read-only search/read

  • list_labels, create_label, label_message, label_thread, unlabel_message, unlabel_thread

  • create_draft, list_drafts — safe, does not send anything

  • send_email — irreversible, sends immediately. The tool description instructs Claude to only use this after you've explicitly confirmed the recipients/subject/body, and it requires a confirmed: true field. Review what Claude is about to send before approving the tool call.

Related MCP server: Gmail & Calendar Multi-Account MCP Server

One-time setup

1. Create a Google Cloud OAuth client (do this once, shared by all accounts/teammates)

  1. Go to the Google Cloud Console and create a new project (or use an existing one).

  2. APIs & Services > Library — search for and enable the Gmail API.

  3. APIs & Services > OAuth consent screen (called Audience in newer Console layouts):

    • User type / Audience: External (if your Google Cloud project belongs to a Google Workspace org, it may default to Internal, which blocks personal @gmail.com accounts with Error 403: org_internal — switch it to External).

    • Publishing status: Production — do not leave it in Testing. Testing-status unverified apps have a Google policy quirk where refresh tokens expire after 7 days, which would silently break every connected account weekly. Production status (even without going through Google's verification review) doesn't have that limit.

    • Tradeoff: since the app won't be verified by Google, everyone who runs npm run add-account will see a "Google hasn't verified this app" warning during sign-in. Click Advanced > Go to <project name> (unsafe) to proceed — this is expected and safe since it's your own app talking to your own Google account.

  4. APIs & Services > Credentials > Create Credentials > OAuth client ID:

    • Application type: Desktop app

    • Note the generated Client ID and Client Secret — you'll enter these in step 3 below.

Share the Client ID/Secret with your teammate out-of-band (password manager, not Slack/email in plaintext, and never commit them to git). Both of you use the same client ID/secret; each person still does their own separate Google sign-in per account.

2. Install and build

Requires Node.js 18 or later.

git clone git@github.com:m-ishit/gmail-mcp-server.git
cd gmail-mcp-server
npm install
npm run build

3. Configure the OAuth client credentials

npm run setup

Paste in the Client ID and Client Secret from step 1. This writes them to a local config file outside the repo (see Where things are stored below) — never committed to git.

4. Connect your Gmail account(s)

npm run add-account

This opens your browser to Google's consent screen. Sign in and approve access. Repeat this command once for each Gmail address you want to connect (personal, work, etc.).

Run npm run add-account again at any time to add another account or to re-authorize one whose access was revoked.

5. Register the server in Claude Desktop

Edit your claude_desktop_config.json:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Add (merge with any existing mcpServers entries):

macOS:

{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": ["/absolute/path/to/gmail-mcp-server/dist/src/index.js"]
    }
  }
}

Windows:

{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": ["C:/absolute/path/to/gmail-mcp-server/dist/src/index.js"]
    }
  }
}

Use the absolute path to your clone of this repo. Forward slashes work fine in these args on Windows too.

Fully quit and reopen Claude Desktop (not just close the window) so it picks up the new server.

6. Try it

In a Claude Desktop conversation:

"List my connected Gmail accounts"

"Search my alice@gmail.com inbox for unread emails from the last week"

For a second machine / teammate (e.g. Windows)

Repeat steps 2–6 above on their machine:

  • Same Client ID/Secret from step 1 (shared with them securely).

  • They run npm run add-account for their own Gmail addresses — this creates their own local tokens, separate from yours.

  • They edit their own claude_desktop_config.json with their own path to dist/src/index.js.

No account credentials or tokens are ever shared between machines — only the OAuth client ID/secret (which identifies the application, not any individual user).

Where things are stored

All secrets live outside this repo, under your OS's application-data directory:

  • macOS: ~/Library/Application Support/gmail-mcp-server/

  • Windows: %APPDATA%\gmail-mcp-server\

  • Linux: $XDG_CONFIG_HOME/gmail-mcp-server/ (or ~/.config/gmail-mcp-server/)

Two files:

  • config.json — your OAuth client ID/secret

  • accounts.json — one refresh token per connected Gmail address (never the access token, which is short-lived and re-derived automatically on each call)

On macOS/Linux these files are written with chmod 600 (owner read/write only). On Windows, protection instead relies on the file living under your own Windows user profile (%APPDATA%), which other local user accounts can't read by default — this is a different protection model than POSIX permissions, not a strict equivalent.

Never commit dist/, node_modules/, or any copy of these config files to git.

Security notes

  • Requested Gmail scopes are gmail.modify (read/search/labels/drafts) and gmail.send — not the broader full-mailbox-access scope, and never permanent-delete access.

  • Tokens are never printed to logs; the logger redacts token-shaped fields and only ever writes to stderr (stdout is reserved for the MCP protocol channel).

  • send_email is irreversible. Read its tool description in the tools list, and always check the recipients/subject/body Claude shows you before approving that specific tool call.

  • If you ever suspect a token has leaked, revoke access at myaccount.google.com/permissions and run npm run add-account again to re-authorize.

Troubleshooting

  • "No OAuth client credentials found" — run npm run setup first.

  • "Account is not connected to this server" — run npm run add-account for that address.

  • Google didn't return a refresh token — go to myaccount.google.com/permissions, remove this app's access for that account, and run npm run add-account again (the consent screen forces re-issuing a refresh token).

  • Tool calls fail with a 401/403 — the account's access may have been revoked; reconnect it with npm run add-account.

  • Use npm run inspect to open the MCP Inspector and manually exercise each tool without needing Claude Desktop running.

Contributing

Issues and pull requests are welcome. This is a small, focused tool — please open an issue to discuss significant changes before submitting a large PR.

If you fork this to run your own instance, provision your own Google Cloud OAuth client rather than reusing anyone else's (see One-time setup above) — client secrets for Desktop-app OAuth clients aren't meant to be shared across unrelated users/orgs.

License

MIT

Available Tools

13 tools
create_draftCreate a Gmail draftA

Create a draft email in the account's Drafts folder. This does NOT send anything — it's safe to call freely, including when you're not fully sure the user wants to send yet. The user reviews and sends the draft themselves from Gmail.

Inputs: to (required), account (required), subject (required), bodyText (required), +4 more.

create_labelCreate a Gmail labelA

Create a new Gmail label. Fails with a clear message if a label with that exact name already exists.

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

get_messageGet a Gmail messageA
Read-only

Fetch a single Gmail message by ID, including decoded plain-text/HTML body and attachment metadata (filenames and sizes, not the attachment contents themselves).

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

get_threadGet a Gmail threadA
Read-only

Fetch a full Gmail thread by thread ID, including every message's headers and decoded body text. Use search_threads first to find the thread ID.

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

label_messageApply labels to a messageA
Idempotent

Apply one or more existing labels to a single Gmail message. Label IDs come from list_labels.

Inputs: account (required), labelIds (required), messageId (required).

label_threadApply labels to a threadA
Idempotent

Apply one or more existing labels to every message in a Gmail thread. Label IDs come from list_labels.

Inputs: account (required), labelIds (required), threadId (required).

list_accountsList connected Gmail accountsA
Read-only

List all Gmail accounts currently connected to this server. Call this first whenever it's unclear which account a request should use, and ask the user to clarify if more than one account could match.

Inputs: no named parameters.

list_draftsList Gmail draftsA
Read-only

List existing drafts for an account, with basic metadata (subject, recipient, snippet).

Inputs: account (required), pageToken, maxResults.

list_labelsList Gmail labelsA
Read-only

List all Gmail labels (system labels like INBOX/UNREAD and user-created labels) for an account.

Inputs: account (required).

search_threadsSearch Gmail threadsA
Read-only

Search Gmail threads using Gmail's search syntax (e.g. from:x@y.com is:unread newer_than:7d, subject:invoice has:attachment). Returns thread IDs with a snippet and basic metadata for each matching thread.

Inputs: query (required), account (required), pageToken, maxResults.

send_emailSend an email (irreversible)A
Destructive

⚠️ IRREVERSIBLE: Sends a real email immediately on behalf of the user — there is no undo, no "are you sure" prompt from Gmail, and no draft-review step once this is called. Only call this tool after the human user has explicitly and unambiguously confirmed the exact recipient(s), subject, and body of THIS specific email in the current conversation. If there is any ambiguity about content, recipients, or intent — or if you have not shown the user the exact text you're about to send — use create_draft instead and ask the user to review and send it themselves. Never call this proactively, as part of a speculative multi-step plan, or based on inferred rather than explicitly stated intent.

Inputs: to (required), account (required), subject (required), bodyText (required), +5 more.

unlabel_messageRemove labels from a messageB
Idempotent

Remove one or more labels from a single Gmail message.

Inputs: account (required), labelIds (required), messageId (required).

unlabel_threadRemove labels from a threadA
Idempotent

Remove one or more labels from every message in a Gmail thread.

Inputs: account (required), labelIds (required), threadId (required).

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 13 tools

    Disambiguation5/5

    Each tool targets a distinct Gmail operation (drafting, sending, labeling, searching, listing) with clear boundaries. The only similar pairs (label_message/label_thread, unlabel_message/unlabel_thread) operate on different entities, and send_email has an explicit warning to distinguish it from create_draft.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with underscores (create_draft, search_threads, unlabel_message, etc.), making it easy to predict the function of each tool based on its name.

    Tool Count5/5

    13 tools is appropriate for a Gmail MCP server, covering essential operations without being overwhelming. It's well-scoped for the domain.

    Completeness4/5

    The set provides solid CRUD-like coverage for emails and labels, including create, read, search, label, and send. Minor gaps exist (e.g., no ability to trash/delete messages or edit drafts), but these do not severely hinder typical email workflows.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Lets Claude Desktop manage multiple Gmail accounts simultaneously, supporting search, read, send, reply, and label organization via MCP tools.
      105 npm
      19
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Connects multiple Gmail and Google Calendar accounts to Claude Desktop locally, enabling email management (search, send, draft, label) and calendar operations (list events, search) via natural language.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables Claude to read, search, send, draft, and organize email across multiple independently authenticated Gmail accounts through one local MCP connection. It supports account aliases, per-account default From addresses, dry-run sends, and draft-only replies for safer multi-account email management.
      105 npm
      MIT