Which integrations are available for this server?

Provides least-privilege access to a Gmail inbox for searching emails, reading messages and threads as plain text, and creating draft replies in the original thread without sending them.

How do I use Gmail MCP Server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Gmail MCP Server Search my inbox for the latest email from Stripe and draft a reply asking for an invoice copy" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Gmail MCP Server

by AlexisG1993

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

Gmail MCP Server

Least-privilege Gmail access for AI agents over the Model Context Protocol: search, read and draft replies. It never sends.

License: MIT Node.js TypeScript MCP SDK

Related MCP server: Gmail MCP Server

What it is

A small Model Context Protocol (MCP) server, written in TypeScript, that gives an AI agent least-privilege access to one Gmail inbox. The agent can search mail, read messages and threads as clean plain text, and save draft replies in the correct thread. It cannot send, delete, label or archive mail, or change settings. The server runs locally as a stdio subprocess of the MCP client. It uses OAuth credentials that the mailbox owner creates and keeps, and it has no backend, database or third-party service in between.

Architecture

flowchart LR
    A["MCP client<br/>Claude Desktop, Claude Code or an agent"] -- "JSON-RPC over stdio" --> B["gmail-mcp-server<br/>local Node.js process"]
    B -- "HTTPS + OAuth 2.0" --> C["Gmail API"]
    B -. "reads and refreshes" .-> D[("token.json<br/>local disk")]

The client starts the server as a child process and talks to it over stdin and stdout. No network port is opened.
The server calls the Gmail REST API directly with the user's OAuth token, which never leaves the machine.
Every Gmail response is parsed and rendered as plain text before it reaches the model.

Module	Responsibility
`src/index.ts`	Entry point: stdio transport, protection of the stdout stream
`src/server.ts`	`McpServer` setup, tool registration, zod input schemas, error-to-result mapping
`src/gmail/client.ts`	Authenticated Gmail client, token persistence and refresh, retry policy
`src/gmail/parse.ts`	MIME tree walking, base64url and charset decoding, HTML-to-text, output formatting
`src/gmail/draft.ts`	RFC 2822 reply builder: recipients, subject, threading headers, encoding
`src/gmail/errors.ts`	Classification of Gmail API errors into readable messages
`src/auth.ts`	One-time OAuth sign-in (`npm run auth`)
`src/config.ts`	Scopes, environment variables and file paths

Tools

Tool	What it does	Read-only
`search_emails`	Searches the mailbox with Gmail query syntax and returns a summary per message	Yes
`get_email`	Reads one message: headers, plain-text body, attachment metadata	Yes
`get_thread`	Reads every message in a thread, oldest first	Yes
`create_draft_reply`	Saves a plain-text reply as a draft in the original thread. Never sends.	No (creates drafts only)

All inputs are validated with zod before any Gmail call. Invalid input returns a validation error to the model; Gmail is never called with it. Each tool declares MCP annotations: readOnlyHint: true on the three read tools, and readOnlyHint: false, destructiveHint: false, idempotentHint: false on create_draft_reply.

`search_emails`

Parameter	Type	Default	Constraints
`query`	string	`in:inbox`	Gmail search syntax, 1 to 500 characters
`max_results`	integer	`10`	1 to 25

Returns id, threadId, from, to, subject, date, snippet and labels for each match, newest first.

1 message(s) matching "in:inbox":

1. Ticket #123
   id: m-meta
   threadId: t-200
   from: Support <support@vendor.example>
   to: me@example.com
   date: Sun, 1 Nov 2026 18:00:00 +0000
   labels: INBOX, CATEGORY_UPDATES
   snippet: We've received your request & will reply soon

`get_email`

Parameter	Type	Constraints
`message_id`	string	Gmail id: letters, digits, `-` or `_`, up to 64 characters

Returns From, To, Cc, Subject, Date and Message-ID; the body as plain text; and each attachment's name, type and size. Attachment content is never downloaded.

Message ID: m-nested
Thread ID: t-100
From: Alice Example <alice@example.com>
To: me@example.com
Cc: Carol <carol@example.com>
Subject: Quarterly invoice
Date: Mon, 2 Nov 2026 09:15:00 +0000
Message-ID header: <CAF1234@mail.example.com>
Attachments (metadata only):
- logo.png (image/png, 2.0 KB)
- invoice-2026-11.pdf (application/pdf, 179.2 KB)

See the attached invoice. Total: 1 200 €. 👍

Body extraction:

Walks the full MIME tree, including nested multipart/* parts.
Decodes base64url and the declared charset (for example ISO-8859-1).
Prefers text/plain. Falls back to text/html, converted with a light tag strip.
Truncates bodies over 20,000 characters and says so in the output.

`get_thread`

Parameter	Type	Constraints
`thread_id`	string	Gmail id, same rules as `message_id`

Returns every message in the thread, oldest first, each in the get_email format.

`create_draft_reply`

Parameter	Type	Constraints
`message_id`	string	The message being replied to
`body`	string	Plain text, 1 to 50,000 characters, not whitespace-only. Kept exactly as written.

The draft is built as follows:

Field	Rule
Recipient	The original's `Reply-To` if present, otherwise `From`. If the original is the user's own sent message, its recipients instead. Sender only, never reply-all.
Subject	Prefixed with `Re:` , unless it already starts with `Re:` in any case
Threading	`threadId`, `In-Reply-To` set to the original Message-ID, and `References` set to the original chain plus that Message-ID
Encoding	RFC 2047 for non-ASCII subjects and display names; UTF-8 body with base64 transfer encoding; `raw` sent as base64url

Draft reply created. It has not been sent.
Draft ID: <id assigned by Gmail>
Thread ID: 18c2e9f8a7b6c5d4
To: Billing Team <billing@example.com>
Subject: Re: Invoice #4711 follow-up
Review and send it from Gmail Drafts.

Security model

Scopes

The server requests exactly two OAuth scopes:

Scope	Used for
`https://www.googleapis.com/auth/gmail.readonly`	Searching and reading messages and threads
`https://www.googleapis.com/auth/gmail.compose`	Creating drafts

Gmail has no scope that allows creating drafts without also allowing sending: gmail.compose permits both. Least privilege is therefore enforced in two layers:

The narrowest scopes Gmail offers for this feature set. No gmail.modify and no full mail.google.com access, so the token cannot delete mail, change labels or change settings.
No send tool. The only write operation in the code is users.drafts.create, and a person reviews and sends each draft from Gmail.

The second layer is a property of this code, not of the token. Anyone who obtains token.json could send mail as the user, so treat it like a password.

Controls

Risk	Control
The agent sends mail in the user's name	No send tool. Replies are saved as drafts for a person to review and send.
The agent deletes or alters mail	No `gmail.modify` or full-access scope, and no delete, label or archive tools
Prompt injection through email content	Email is untrusted input to the model. With this tool set, the worst outcome is an unwanted draft, never a sent or deleted message.
Header injection through a crafted original	CR/LF is stripped from every header value copied from the original message, so `Hi\r\nBcc: attacker@example.com` stays a harmless subject
Malicious attachments	Attachment content is never downloaded; only name, type and size are returned
Token leakage	`credentials.json`, `token.json` and `.env` are git-ignored. The token is written atomically with mode `0600` on POSIX systems. Raw Google client errors, which include the `Authorization` header, are never logged or returned.
Sensitive data in logs	Logs contain the tool name, outcome and duration only, never queries, addresses or message content
Third-party data exposure	Local stdio process. The mailbox owner creates the OAuth client in their own Google Cloud project, and no intermediary service holds tokens.

Access can be revoked at any time at myaccount.google.com/permissions.

Setup

Requirements

Node.js 22.12 or later
A Google account
A Google Cloud project you control (free)

1. Create the OAuth client in Google Cloud

In Google Cloud Console, create a project, or select an existing one.
Enable the Gmail API: APIs & Services > Library > Gmail API > Enable.
Configure the OAuth consent screen (Google Auth Platform):
- User type: External.
- Publishing status: Testing.
- Add the Gmail address you will use under Test users.
Create credentials: Clients > Create client, application type Desktop app.
Download the client JSON and save it as credentials.json in the project root.

Note: while the project is in Testing status, Google expires refresh tokens after 7 days, and the tools then ask you to run npm run auth again. Removing that limit requires publishing the app. Both scopes are classed as restricted by Google, so a public app needs Google's verification, which can include a third-party security assessment. For a single internal mailbox, Testing status or a Google Workspace internal app is the practical option.

git clone https://github.com/AlexisG1993/mcp_gmail.git
cd mcp_gmail
npm install
npm run auth     # builds, opens the browser, saves token.json
npm run build

npm run auth:

uses the OAuth loopback flow with PKCE and a state check;
verifies that both scopes were granted;
makes one read-only call to confirm access, and prints the signed-in address.

Configuration

Variable	Default	Purpose
`GMAIL_CREDENTIALS_PATH`	`<project>/credentials.json`	OAuth client file downloaded from Google Cloud
`GMAIL_TOKEN_PATH`	`<project>/token.json`	Saved token, written by `npm run auth` and refreshed automatically

Relative paths are resolved against the project root, not the working directory, because MCP clients start servers from arbitrary directories.

Connect to Claude

Use the absolute path to dist/index.js. On Windows, forward slashes work (C:/Users/you/mcp_gmail/dist/index.js).

Claude Desktop

Edit claude_desktop_config.json:

OS	Location
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`

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

Add an "env" object with GMAIL_CREDENTIALS_PATH and GMAIL_TOKEN_PATH only if the files are not in the project root. Restart Claude Desktop afterwards.

Claude Code

claude mcp add --transport stdio gmail -- node /absolute/path/to/mcp_gmail/dist/index.js

To keep the files elsewhere, add --env GMAIL_TOKEN_PATH=/secure/path/token.json (and likewise for credentials) before the server name.

Triage demo

examples/triage-demo.ts shows the server used by an agent pipeline instead of a chat client.

It starts the server over stdio with the official MCP client.
It reads the 10 most recent inbox emails through search_emails and get_email.
It asks Claude to classify each one, using structured JSON output validated against a zod schema:
- type: customer, vendor, admin or other
- priority: high, normal or low
It prints a table with a one-line reason for each classification.

export ANTHROPIC_API_KEY=...       # PowerShell: $env:ANTHROPIC_API_KEY = "..."
npm run demo

The demo also reads a git-ignored .env file in the project root; variables already set in the shell take precedence.

Variable	Default	Purpose
`ANTHROPIC_API_KEY`	(required)	Claude API key
`TRIAGE_MODEL`	`claude-haiku-5-5`	Claude model used for classification

The model is a setting, not a code change. Classification is a small, high-volume task, so the default is the lowest-cost current model. Set TRIAGE_MODEL=claude-sonnet-5-5 or claude-opus-5-5 to compare quality against cost on the same inbox. For models that support it, a request declined by a safety classifier is automatically retried on a fallback model. With other models, a declined email is shown as such in the table.

The demo calls only read tools. It passes the server only the Gmail path variables, never the API key. It also tells the model to treat email content as untrusted data, never as instructions.

Design decisions

stdio transport. The server is a child process of the MCP client on the user's machine. It opens no network port, so there is no listener to authenticate or expose. The OAuth token stays on the same machine as the user. stdout carries only the MCP protocol: all logging goes to stderr, and console.log is redirected to stderr so a dependency cannot corrupt the stream.

Plain-text output. Tools return labelled plain text, not raw Gmail JSON. Models read it reliably, it costs far fewer tokens than the API's nested MIME structure, and every tool presents emails in the same shape. Decoding, charset handling, HTML stripping and truncation happen once, in tested code, instead of being left to the model.

Drafts instead of sending. Sending is irreversible and acts in the user's name. A draft keeps a person in the loop at the one step where a mistake is costly, while still doing the bulk of the work.

Failure handling.

Gmail errors become tool results with isError: true and a specific message, never a crash. Examples: not found, rate limited, Gmail API not enabled, sign-in expired.
429s, 403 rate-limit errors and 5xx responses are retried with exponential backoff and jitter, at most 3 attempts. Retry-After is honoured, capped at 8 seconds.
The Google client library's own retry is switched off, so this is the only retry policy. Left on, a single failing call can make 12 HTTP requests.
Creating a draft is not retried on 5xx, because Gmail may already have saved it and a retry would create a duplicate.
An expired or revoked sign-in is detected, and the cached client is dropped. Running npm run auth then takes effect without restarting the server.

Minimal dependencies.

Runtime: @modelcontextprotocol/server (MCP TypeScript SDK v2), googleapis, google-auth-library and zod.
No HTML parsing library, no framework, no database.

Limitations

One mailbox per server instance. Each instance runs with one token; multiple mailboxes need multiple configured instances.
Plain-text drafts only. Drafts have no HTML formatting and no attachments, and replies go to the sender only (no reply-all).
No attachment content. Attachments are reported by name, type and size only, by design.
Bounded output. Bodies are truncated at 20,000 characters, and search returns at most 25 results with no pagination.
Light HTML conversion. It suits typical email but is not a renderer; complex layouts lose some structure.
Testing-mode tokens. Unpublished Google Cloud projects expire refresh tokens after 7 days.

From demo to production

This server lets an agent work an inbox on request. A production triage system that processes every incoming email unattended needs more:

Capability	Purpose
Push notifications	Call `users.watch` to have Gmail publish mailbox changes to a Cloud Pub/Sub topic, processed by a subscriber, instead of polling.
historyId checkpoints	Each notification carries a `historyId`. Persist the last processed one and fetch changes since then with `users.history.list`, so nothing is missed across restarts. If the stored id is too old (Gmail returns 404), fall back to a full sync.
Idempotent ticket ledger	Pub/Sub delivers at least once. Record each Gmail message id before acting on it, so a redelivered notification never creates a second ticket or draft.
Dead-letter queue	Messages that keep failing (parse errors, model errors, downstream outages) move to a DLQ after a bounded number of attempts, for inspection and replay, without blocking the stream.
Daily reconciliation sweep	A scheduled job compares recent inbox messages with the ledger and catches anything a dropped notification or outage missed.
Watch renewal	A watch expires after 7 days. Renew it on a schedule; Google recommends daily, which leaves a wide safety margin.
Deployment	Run as a service with secrets in a secret manager. For a Google Workspace domain, use a service account with domain-wide delegation instead of a personal OAuth token. Add metrics and alerting on queue depth, error rate and watch expiry.

Troubleshooting

Message or symptom	Cause and fix
`OAuth client file not found at ...`	`credentials.json` is missing. Download the Desktop app client from Google Cloud and save it in the project root, or set `GMAIL_CREDENTIALS_PATH`.
`... is not a Desktop app OAuth client file`	The client was created as a Web application. Create a Desktop app client instead.
Google shows "Access blocked" or "has not completed the Google verification process"	Your address is not a test user. Add it under Google Auth Platform > Audience > Test users.
`Sign-in did not grant all required permissions`	A permission was unticked on the consent screen. Run `npm run auth` again and leave every Gmail permission ticked.
`No saved Gmail token found at ...`	Sign-in has not been done for this path. Run `npm run auth`.
`The saved Gmail sign-in has expired or was revoked.`	Usually the 7-day Testing-mode expiry. Run `npm run auth`; no restart is needed.
`The Gmail API is not enabled for this Google Cloud project.`	Enable the Gmail API under APIs & Services > Library.
`Gmail rate limit reached, even after retrying.`	Gmail is throttling the account. Wait a minute and retry.
The client shows no Gmail tools	Check that the config path points to `dist/index.js`, that `npm run build` has been run, and restart the client. Server logs go to stderr, which Claude Desktop writes to its MCP log files.

Development

Script	What it does
`npm run build`	Compiles TypeScript to `dist/`
`npm start`	Runs the server on stdio (normally started by the MCP client instead)
`npm run auth`	Builds, then runs the one-time OAuth sign-in
`npm test`	Runs the test suite
`npm run typecheck`	Strict type-check of source, tests and examples
`npm run demo`	Builds, then runs the triage demo

src/
  index.ts           entry point, stdio transport
  server.ts          McpServer setup and tool registration
  auth.ts            one-time OAuth flow (npm run auth)
  config.ts          scopes, env vars and paths
  log.ts             stderr logger
  gmail/
    client.ts        authenticated Gmail client, retries
    parse.ts         MIME and body parsing, output formatting
    draft.ts         RFC 2822 reply builder
    errors.ts        Gmail error classification
tests/
  fixtures/          Gmail-shaped JSON responses
  parse.test.ts      MIME parsing
  draft.test.ts      reply building
  errors.test.ts     error handling and retries
  server.test.ts     input validation and tool results
examples/
  triage-demo.ts     MCP client + Claude API classification

Tests

npm test            # vitest, no network access
npm run typecheck   # strict TypeScript, source, tests and examples

The tests run without network access, using small JSON fixtures shaped like real Gmail API responses.

Area	Coverage
MIME parsing	Plain-only, HTML-only, `multipart/alternative`, nested multipart with attachments, attached `.eml` files, non-UTF-8 charsets, base64url edge cases (padding, URL-safe alphabet, multi-byte characters), truncation at the 20,000-character boundary
Draft building	Recipient selection, `Re:` handling, `In-Reply-To` and `References`, `threadId`, header-injection attempts, RFC 2047 encoding of non-ASCII subjects and names, line-length limits, base64url output
Reliability	Error classification and messages, auth-failure detection, retry behaviour (what is retried, the attempt cap, backoff ranges, the `Retry-After` cap)
Input validation	Defaults, bounds and rejection cases for every tool's schema, and an assertion that nothing is ever written to stdout

License

MIT. See LICENSE. Release notes are in CHANGELOG.md, and security reports are handled as described in SECURITY.md.

Available Tools

4 tools

create_draft_replyCreate a draft replyA

Save a plain-text reply to an email as a Gmail draft, in the same thread, addressed to the original sender (its Reply-To if set). Nothing is sent: a person reviews and sends the draft from Gmail.

Name	Required	Description	Default
`body`	Yes	Plain-text body of the reply. It is saved as a draft and never sent.
`message_id`	Yes	Id of the email being replied to, as returned by search_emails or get_email.

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), the description discloses the important behavioral facts: the reply lands in the same thread, the recipient is derived from Reply-To, and nothing is transmitted externally until a human sends it. It does not address whether repeated calls create duplicate drafts, which is relevant given idempotentHint=false.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with no waste; the operation and its key constraint (nothing is sent) are front-loaded, and the parenthetical Reply-To detail is compactly integrated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter tool with full schema coverage and annotations, the description covers purpose, thread/recipient behavior, and the no-send guarantee. The one gap is the return value: with no output schema, an agent cannot tell whether it receives a draft id or thread id from the call.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics: the body is plain-text only, and message_id implicitly determines both the thread and the recipient (no separate recipient parameter exists). That explains a non-obvious consequence of a parameter beyond its schema text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Save a plain-text reply ... as a Gmail draft') plus the scope details (same thread, addressed to original sender/Reply-To). This is clearly a draft-creation write operation, unmistakable from the read-only siblings search_emails, get_email, and get_thread.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'Nothing is sent: a person reviews and sends the draft from Gmail' establishes the context in which this tool is appropriate (human-in-the-loop drafting) and implicitly rules out use as an auto-send mechanism. It does not name an alternative send tool or state exclusions explicitly, so it stops short of full routing guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_emailRead an emailA

Read-only

Read one email: headers, plain-text body (HTML converted to text if there is no plain part) and attachment names and sizes. Attachment contents are never returned.

Name	Required	Description	Default
`message_id`	Yes	Message id, as returned by search_emails.

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds genuinely useful behavioral facts beyond that: HTML bodies are converted to text when no plain part exists, and attachment contents are never returned, which prevents an agent from promising file contents it cannot get.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with no filler. The most decision-relevant fact for an agent (what comes back, and that attachment contents do not) is front-loaded in the first sentence, and the negative constraint is isolated in the second.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description does the job of describing the return payload: headers, body in text form, attachment names and sizes. It falls just short of complete by omitting any notion of body size limits, truncation, or failure modes for invalid ids on a tool flagged openWorldHint.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for the single message_id parameter, including a pattern and a note on where ids come from, so the schema carries the parameter burden. The description adds nothing further about the identifier format or what happens with a malformed or stale id, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

"Read one email" states a specific verb and resource, and "one" distinguishes it from the sibling search_emails, which returns many. It doesn't explicitly name the siblings it competes with (get_thread, search_emails), so differentiation is implied rather than spelled out.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: the schema note "as returned by search_emails" suggests the read-after-search flow, and "one email" signals this is the single-message path rather than the thread or search path. There is no explicit when-to-use/when-not statement and no mention of error behavior for unknown ids.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_threadRead a threadA

Read-only

Read every message in a thread, oldest first, each in the same format as get_email.

Name	Required	Description	Default
`thread_id`	Yes	Thread id, as returned by search_emails or get_email.

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuine behavior beyond that: deterministic oldest-first ordering, full-thread coverage ("every message"), and a per-message format identical to get_email, which lets an agent parse results without guessing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One sentence, front-loaded with the core action, with the ordering and format details packed in without waste. Nothing is redundant or padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only, one-parameter tool with full schema coverage and annotations, the description supplies what matters: ordering, completeness, and return format by reference to get_email. It does not address behavior on very large threads (truncation or limits), which is the only notable omission.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single thread_id parameter is fully documented in the schema, including its pattern and where the id comes from. The description adds nothing about the parameter, which is acceptable given the schema already does that work.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

"Read every message in a thread" gives a specific verb (read) and resource (thread), and adds scope (all messages) and ordering (oldest first). It implicitly contrasts with get_email by pointing to that tool's format, though it never names search_emails as the tool for finding a thread id.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied: call it when you have a thread_id and want the whole conversation rather than a single message. There is no explicit when-not guidance, no mention that the thread_id comes from search_emails/get_email (that lives only in the schema), and no stated alternative.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_emailsSearch emailsA

Read-only

Search the mailbox with Gmail search syntax. Returns id, threadId, from, to, subject, date, snippet and labels for each match, newest first.

Name	Required	Description	Default
`query`	No	Gmail search syntax, e.g. "from:alice is:unread newer_than:7d". Defaults to "in:inbox".	in:inbox
`max_results`	No	How many messages to return, 1 to 25.

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the read-only and open-world annotations, it discloses the exact fields returned for each match and the newest-first ordering. Listing snippet rather than body also helps set expectations that results are summaries, though no further operational behavior is described.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two compact sentences front-load the operation and query syntax, then provide useful result and ordering details. There is no redundant or unnecessary wording.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple search tool with two optional, fully documented parameters, the combined definition supplies the invocation model, defaults, result bounds, returned fields, and ordering. Explicit sibling routing would improve selection guidance but is not essential to invoking the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and both parameters already document their syntax, defaults, and limits. The description repeats the Gmail-syntax point but adds no parameter meaning beyond the schema, so the baseline score applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

“Search the mailbox with Gmail search syntax” gives a specific verb, resource, and query model. The operation is clearly a search rather than a single-item retrieval or draft mutation, but the description does not explicitly differentiate itself from the named siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The Gmail-syntax query context makes it clear that this tool is for finding matching messages. It does not explicitly direct agents to get_email for full message content or get_thread for conversation context, nor state other exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

4 tool updatesv0.1.0Nov 3, 2026
- First observedcreate_draft_reply
- First observedget_email
- First observedget_thread
- First observedsearch_emails

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4/5.0

Scored 2026-11-03 05:55 across 4 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: search messages, read a single email, read a thread, or create a draft reply. There is no ambiguous overlap; get_email and get_thread differ by message vs. thread scope and descriptions make that clear.

Naming Consistency5/5

All names use consistent snake_case verb_noun phrasing. The pattern is predictable across search_emails, get_email, get_thread, and create_draft_reply.

Tool Count4/5

Four tools is a reasonable, focused set for a read-and-draft-reply workflow. It is slightly thin for a Gmail server overall, but each included tool earns its place.

Completeness3/5

The set covers searching, reading, thread reading, and saving draft replies, but omits core Gmail operations such as sending, label management, deletion/trash, and attachment retrieval. These are notable gaps for an agent expecting general Gmail functionality.

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

Related MCP Connectors

Mailows
com.mailows
Give AI agents their own email inboxes: list, read and send mail via scoped, revocable OAuth grants.
Email Autonomous Agents Security
1
https://mcp.mailows.com/mcp
Mailera
app.mailera
Email for AI agents: read, search and send from your Gmail, Outlook, Yahoo, iCloud or IMAP inbox.
Email Communication
1
https://mailera.app/api/public/v1/mcp
sebastianall1977-gmail-mcp
ai.smithery
Manage Gmail end-to-end: search, read, send, draft, label, and organize threads. Automate workflow…
Communication App Automation Workplace & Productivity
2
https://server.smithery.ai/@sebastianall1977/gmail-mcp/mcp
Higgs Hub B
pro.higgshub
Gmail, Outlook, Drive, OneDrive and calendars for AI agents. Many accounts, one endpoint, audit log.
Calendar Management Cloud Storage Email
1461
https://higgshub.pro/api/mcp/mcp

Related MCP Servers

Gmail MCP Server
Communication App Automation Workplace & Productivity
MCP-Mirror
A
license
Not graded
quality
Not graded
maintenance
Enables AI assistants to interact with Gmail through natural language, supporting email sending/reading, searching, draft management, label organization, and batch operations with secure OAuth authentication.
Updated a year ago (2025-06-25 18:48 UTC)
-
Gmail MCP Server
Communication App Automation
JaviEzpeleta
A
license
Not graded
quality
D
maintenance
Enables AI assistants to interact with Gmail through OAuth2 authentication, allowing users to list, search, read emails, and create drafts with a safety-first design that prevents accidental sends by default.
Updated a year ago (2025-08-07 20:55 UTC)
208 npm
MIT
gmail-mcp-server
Email Communication
ktsenapathy
A
license
Not graded
quality
D
maintenance
Enables AI assistants to read unread Gmail messages and create threaded draft replies, without ever sending email automatically.
Updated 7 months ago (2026-03-20 13:40 UTC)
MIT
Gmail MCP Server
Email Communication
TheTymur
A
license
Not graded
quality
B
maintenance
Enables AI agents to manage Gmail accounts, including reading and searching emails, creating and sending drafts, and handling labels, blocks, and unsubscribes.
Updated a month ago (2026-09-27 17:26 UTC)
MIT

Gmail MCP Server

Contents

What it is

Architecture

Tools

search_emails

get_email

get_thread

create_draft_reply

Security model

Scopes

Controls

Setup

Requirements

1. Create the OAuth client in Google Cloud

2. Install, sign in and build

Configuration

Connect to Claude

Claude Desktop

Claude Code

Triage demo

Design decisions

Limitations

From demo to production

Troubleshooting

Development

Tests

License

Available Tools

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

`search_emails`

`get_email`

`get_thread`

`create_draft_reply`