This server provides Gmail and Google Drive integration through three tools:
send_email: Send emails from your configured Gmail account to recipients via to, cc, and bcc fields (comma-separated), with plain text or HTML body support. Returns the Gmail message ID and thread ID on success.
search_emails: Search your Gmail using standard query syntax (e.g., has:attachment from:bob newer_than:7d), returning message summaries (ID, sender, recipient, subject, date, snippet) and attachment metadata (attachment ID, filename, MIME type, size). Configurable result limit (default: 10).
download_attachment: Download a specific email attachment (identified by message_id plus optional filename or attachment_id) and upload it directly to a Google Drive folder (default: Gmail Attachments, auto-created if absent). Returns the Drive file ID, name, and shareable web view link.
Allows sending emails from Gmail/Workspace address with support for HTML, cc/bcc, searching Gmail with advanced queries, and downloading attachments.
Uploads downloaded email attachments to a Google Drive folder, returning the Drive link.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@gmail-mcp Search my Gmail for unread emails from last week."
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.
A local stdio MCP server that gives your local Claude clients these Gmail tools:
Tool | What it does |
| Send mail from your Gmail/Workspace address (plain or HTML, cc/bcc). Every send is logged. |
| Search Gmail ( |
| Pull an attachment from a message and upload it to your Google Drive, returning the Drive link. |
| Pull an attachment from a message and save it to a local directory ( |
Local stdio — no public endpoint, no OAuth-for-callers, no server to host. Runs as a subprocess of your Claude client.
Single Google account for both Gmail and Drive.
Least-privilege scopes — gmail.send, gmail.readonly, drive.file (the app only ever sees
Drive files it created).
Credentials in AWS SSM — the refresh token lives in an SSM SecureString and is fetched at
launch; nothing is written to disk. Requires AWS credentials at runtime (e.g. an AWS_PROFILE).
Attachments upload into a Drive folder named Gmail Attachments by default (created on first
use; override per call with the drive_folder argument).
Related MCP server: Gmail Local MCP
uv (manages Python 3.12 + deps).
AWS credentials with read/write access to the SSM parameter (any standard method — AWS_PROFILE,
env vars, instance role). A region from your AWS config, env AWS_REGION, or GMAIL_MCP_AWS_REGION.
A Google Cloud project with the Gmail API and Google Drive API enabled (Console → APIs & Services → Library).
A Google OAuth client of type "Desktop app" — download its client_secret.json
(Console → APIs & Services → Credentials).
Runs a browser consent for the three scopes and stores the credentials in SSM
(default param /gmail-mcp/authorized-user-json).
cd /path/to/gmail-mcp
# Using a downloaded Desktop client_secret.json:
AWS_PROFILE=<your-aws-profile> \
uv run python scripts/mint_token.py --client-secrets-file /path/to/client_secret.json
# ...or reuse an existing Google token already in SSM (its client_id/secret):
AWS_PROFILE=<your-aws-profile> \
uv run python scripts/mint_token.py --client-secrets-ssm-param /path/to/existing-tokenA browser window opens — approve access for the intended account. On success the token is written to SSM and the server can run.
Replace /path/to/gmail-mcp and <your-aws-profile> with your values.
claude mcp add gmail-mcp -s user \
-e AWS_PROFILE=<your-aws-profile> \
-- uv run --directory /path/to/gmail-mcp gmail-mcpAdd to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):
{
"mcpServers": {
"gmail-mcp": {
"command": "uv",
"args": ["run", "--directory", "/path/to/gmail-mcp", "gmail-mcp"],
"env": { "AWS_PROFILE": "<your-aws-profile>" }
}
}
}Restart Claude Desktop after editing. The three tools appear under the gmail-mcp server.
"Email alice@example.com with the subject 'Lunch?' and body 'Free tomorrow at 1?'"
"Search my Gmail for emails with attachments from the last week."
"Download the PDF attached to that invoice email into my Drive."
Variable | Default | Purpose |
| — | AWS credentials used to read the token from SSM |
| standard AWS config | Region of the SSM parameter |
|
| SSM param holding the credentials JSON |
|
| Destination Drive folder for downloads |
The server can send mail as you. Every send is logged (recipients, subject, timestamp). There is no recipient allowlist by default; treat the tool as injection-sensitive.
The refresh token never touches disk — only an SSM SecureString, fetched in-memory at launch.
Scopes are least-privilege: read Gmail, send Gmail, and Drive access limited to app-created files.
uv sync
uv run pytest # unit tests (all mocked; no live Google/AWS calls)
uv run ruff check . # lintLayout: src/gmail_mcp/ — auth.py (SSM→credentials), gmail_client.py (send/search/attachments),
drive_client.py (folder + upload), attachments.py (orchestration), server.py (FastMCP wiring),
bootstrap.py (token mint).
Download an attachment from a Gmail message and upload it to Google Drive.
Identify the attachment by `filename` (preferred — stable across requests) or `attachment_id`;
if the message has exactly one attachment, neither is required. Uploads into the Drive folder
`drive_folder` (created if absent). Returns the Drive file id, name, and web_view_link.
| Name | Required | Description | Default |
|---|---|---|---|
| message_id | Yes | ||
| attachment_id | No | ||
| filename | No | ||
| drive_folder | No | Gmail Attachments |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses key behaviors: uploading to Drive, folder creation if absent, and return object fields. Missing details like permission requirements, file size limits, or error handling but covers the main workflow.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with action, every sentence essential. No filler, perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema but description mentions return fields. Covers main functionality and parameter rationale. Minor gaps: no mention of error cases (e.g., missing attachment) or behavior when multiple attachments without identifier. Still highly functional for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds significant meaning beyond the schema: explains how to identify attachment (filename preferred), notes it's not required if one attachment, and clarifies drive_folder is created if absent. The message_id is obvious from context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Download an attachment from a Gmail message and upload it to Google Drive', specifying the verb, resource, and scope. It also distinguishes itself from sibling tools by focusing on attachment download/upload specifically.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on parameter usage: prefer filename, fallback to attachment_id, and not needed if exactly one attachment. However, it does not explicitly state when not to use this tool or mention alternatives like direct download without Drive upload.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Gmail using a standard Gmail query (e.g. 'has:attachment from:bob newer_than:7d').
Returns a list of message summaries: id, from, to, subject, date, snippet, and any attachment
metadata (attachment_id, filename, mime_type, size) needed by download_attachment.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| max_results | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It describes the return format but does not disclose side effects, auth requirements, rate limits, or that this is a read-only operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that front-load the key action and example, followed by a clear list of return fields. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description covers core functionality but misses details about max_results limits, pagination, default behavior, and potential empty results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It provides an example for the 'query' parameter but entirely omits explanation of the 'max_results' parameter, leaving its purpose and behavior ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches Gmail with a standard Gmail query, provides a concrete example, and specifies the return fields including attachment metadata, distinguishing it from sibling tools like download_attachment and send_email.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for searching emails and mentions that the output is needed by download_attachment, but does not explicitly state when to use this tool versus alternatives or provide any exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send an email from the configured Gmail account.
`to`, `cc`, `bcc` accept a single address or a comma-separated list. Set `html=true` to send
`body` as HTML. Returns the Gmail message id and thread id.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | ||
| subject | Yes | ||
| body | Yes | ||
| cc | No | ||
| bcc | No | ||
| html | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that it returns Gmail message id and thread id, and explains address format and HTML toggle, but does not mention side effects, auth needs, rate limits, or failure behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: first sentence states purpose, second provides parameter details and return info. It is front-loaded, concise, and contains no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description covers return values (message id, thread id) and explains key parameters. It lacks error handling and size limits, but for a simple email sending tool it is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the comma-separated list behavior for to/cc/bcc and the html boolean, adding meaning beyond the schema. However, it does not explain subject, body constraints, or provide complete parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Send an email from the configured Gmail account,' specifying the verb and resource. It is distinct from sibling tools (download_attachment, search_emails) which perform different actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by stating its function but provides no explicit guidance on when to use this tool versus alternatives, nor does it mention prerequisites or scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0download_attachmentsearch_emailssend_emailEach tool has a clearly distinct purpose: search, send, and download attachment. No overlap in functionality, making selection unambiguous.
All tools follow a consistent verb_noun pattern in snake_case (search_emails, send_email, download_attachment), with no deviations.
3 tools are appropriate for a basic Gmail MCP, covering core operations (search, send, attachment download). Could be slightly expanded but well-scoped.
Covers essential email tasks but lacks common operations like mailbox listing, labeling, or message deletion. Gaps exist but are not critical for basic usage.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
MCP server for Nylas — read email, calendars, events and contacts, and send email or create events.
Email inboxes for AI agents: send, receive, reply, search, and manage threaded email over MCP.
Connect any mailbox to Claude, ChatGPT & AI: read, send, reply, schedule & search emails.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Warrenn/gmail-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
