Enables programmatic access to Gmail to search emails using Gmail query syntax, list unread messages, archive or mark emails as read, and manage account labels.
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 Server search for unread emails from GitHub from the last 24 hours"
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 Model Context Protocol (MCP) server that provides Gmail access for Claude Code and other MCP clients. Built with FastMCP.
list_unread - List unread emails from inbox
search - Search emails using Gmail query syntax
archive - Archive emails (removes from inbox)
mark_as_read - Mark emails as read without archiving
get_labels - Get all Gmail labels
Related MCP server: Gmail MCP Server
No local installation required! Run directly from GitHub using uvx:
uvx --from git+https://github.com/fred-drake/gmail-mcp gmail-mcpGo to Google Cloud Console
Create a new project or select an existing one:
Click the project dropdown at the top of the page
Click "New Project", give it a name, and create it
Make sure your new project is selected
Enable the Gmail API:
Navigate to "APIs & Services" > "Library"
Search for "Gmail API" and click on it
Click "Enable"
Configure the OAuth consent screen (required before creating credentials):
Go to "APIs & Services" > "OAuth consent screen"
Select "External" as the user type and click "Create"
Fill in the required fields:
App name: Choose any name (e.g., "Gmail MCP")
User support email: Select your email
Developer contact email: Enter your email
Click "Save and Continue"
On the "Scopes" page, click "Save and Continue" (no changes needed)
On the "Test users" page:
Click "Add Users"
Enter the Gmail address you want to access (this is critical!)
Click "Add" then "Save and Continue"
Click "Back to Dashboard"
Create OAuth credentials:
Go to "APIs & Services" > "Credentials"
Click "Create Credentials" > "OAuth client ID"
Choose "Desktop app" as the application type
Give it a name (e.g., "Gmail MCP Desktop")
Click "Create"
Click "Download JSON" to save the credentials file
Store this file securely - you'll need the path for configuration
Set the path to your OAuth credentials file:
export GMAIL_MCP_CREDENTIALS_PATH="/path/to/your/credentials.json"Optionally, customize the token cache location (default: ~/.config/gmail-mcp/token.json):
export GMAIL_MCP_TOKEN_PATH="/custom/path/token.json"Run the interactive setup to authenticate:
uvx --from git+https://github.com/fred-drake/gmail-mcp gmail-mcp --setupThis will open a browser window for Google OAuth authentication. After authorizing, the token will be cached for future use.
Add to your Claude Code MCP settings:
{
"mcpServers": {
"gmail": {
"command": "uvx",
"args": ["--from", "git+https://github.com/fred-drake/gmail-mcp", "gmail-mcp"],
"env": {
"GMAIL_MCP_CREDENTIALS_PATH": "/path/to/your/credentials.json"
}
}
}
}{
"mcpServers": {
"gmail": {
"command": "uvx",
"args": ["--from", "git+https://github.com/fred-drake/gmail-mcp", "gmail-mcp"],
"env": {
"GMAIL_MCP_CREDENTIALS_PATH": "/path/to/your/credentials.json",
"GMAIL_MCP_TOKEN_PATH": "/custom/path/token.json"
}
}
}
}Variable | Required | Default | Description |
| Yes | - | Path to OAuth credentials JSON |
| No |
| Path to token cache file |
List unread emails from inbox.
Parameters:
max_results (int, optional): Maximum emails to return (1-100). Default: 20.
Returns: List of email objects with id, from, subject, date, snippet, labels, body_preview.
Search emails using Gmail query syntax.
Parameters:
query (str): Gmail search query (e.g., "from:user@example.com is:unread")
max_results (int, optional): Maximum results (1-100). Default: 20.
Returns: List of matching email objects.
Example queries:
from:notifications@github.com - Emails from GitHub
is:unread newer_than:1d - Unread emails from last 24 hours
subject:invoice - Emails with "invoice" in subject
has:attachment larger:5M - Emails with attachments over 5MB
Archive emails by removing INBOX and UNREAD labels.
Parameters:
message_ids (list[str]): List of message IDs to archive.
Returns: Dict with archived_count, failed_count, and details.
Mark emails as read without archiving.
Parameters:
message_ids (list[str]): List of message IDs to mark as read.
Returns: Dict with marked_count, failed_count, and details.
Get all Gmail labels for the authenticated user.
Returns: List of label objects with id, name, type, and message counts.
Python 3.13+
Nix (optional, for reproducible environment)
cd gmail-mcp
nix developcd gmail-mcp
pip install -e ".[dev]"pytestruff check .
ruff format .MIT
Archive emails by removing INBOX and UNREAD labels.
Args: message_ids: List of message IDs to archive.
Returns: Dict with archived_count, failed_count, and details.
| Name | Required | Description | Default |
|---|---|---|---|
| message_ids | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the mechanism (label removal) and return structure (archived_count, failed_count), but omits safety/reversibility details, rate limits, or partial failure behavior beyond the return keys.
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?
Docstring-style Args/Returns format is slightly redundant with structured schema fields, but efficient given the lack of schema descriptions. No wasted prose.
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?
For a single-parameter mutation tool, the description adequately covers the parameter, operation semantics, and return structure. Missing only edge-case handling details.
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% (no property descriptions), but the Args section compensates by documenting message_ids as 'List of message IDs to archive,' clarifying the expected input format.
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 defines 'archive' concretely as 'removing INBOX and UNREAD labels,' avoiding tautology. It distinguishes from sibling mark_as_read by specifying both labels are removed (inbox removal is the key differentiator).
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?
No guidance on when to choose this over mark_as_read (which likely only removes UNREAD) or delete. No mention of typical use cases like 'inbox zero' workflows or that archived emails remain searchable via search.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all Gmail labels for the authenticated user.
Returns: List of label objects with id, name, type, and message counts.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Lacks annotations, so the description carries full disclosure burden. It clarifies scope ('all Gmail labels', 'authenticated user') but omits safety confirmation (read-only nature), rate limits, or whether system labels are included. The return value description is redundant since output schema exists.
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?
Front-loaded action sentence followed by return description. Efficient structure with minimal waste, though the Returns sentence adds limited value given the existence of an output schema.
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?
Adequate for a simple read operation with no parameters and existing output schema. Covers the essential operation scope, though additional context on label types (system vs. user) would improve completeness given zero annotation coverage.
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?
Input schema contains zero parameters. Per rubric, baseline score is 4 for zero-parameter tools. The description implicitly confirms no filtering is possible ('all Gmail labels'), which aligns with the empty schema.
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?
Provides specific verb (Get), resource (Gmail labels), and scope (all labels for authenticated user). However, it does not explicitly differentiate from sibling tools like 'search' or 'list_unread' that might also interact with labels in different contexts.
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?
Offers no guidance on when to invoke this tool versus siblings like 'search' or 'list_unread', nor does it mention prerequisites such as requiring OAuth scopes or when label data is needed for subsequent operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List unread emails from inbox.
Args: max_results: Maximum number of emails to return (1-100). Default: 20.
Returns: List of email objects with id, from, subject, date, snippet, labels, body_preview.
| Name | Required | Description | Default |
|---|---|---|---|
| max_results | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full disclosure burden. It successfully documents the return structure (email object fields) and parameter constraints (1-100 range). However, lacks safety context (auth requirements, rate limits) and behavior on empty inbox.
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?
Uses docstring format with Args/Returns sections. First sentence is strong and front-loaded. Returns section may be redundant if rich output schema exists, but structure is logical and information density is high with minimal waste.
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?
Adequate for a single-parameter list operation. Describes the parameter fully and outlines return fields. Lacks completeness on behavioral edge cases and sibling differentiation, which would elevate it for an email tool with multiple query options.
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% (max_results lacks description), but description fully compensates by documenting the parameter semantics, valid range (1-100), and default value (20).
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?
States specific verb (List) + resource (unread emails) + scope (from inbox). Clearly implies read-only operation distinct from mutation siblings like 'archive' and 'mark_as_read', though it doesn't explicitly name alternatives.
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 no explicit guidance on when to use this versus the 'search' sibling, which could also retrieve unread emails. No preconditions or filtering guidance provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark emails as read without archiving.
Args: message_ids: List of message IDs to mark as read.
Returns: Dict with marked_count, failed_count, and details.
| Name | Required | Description | Default |
|---|---|---|---|
| message_ids | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It partially satisfies this by documenting the return structure (marked_count, failed_count, details) in the Returns section, revealing idempotency hints (failed_count suggests partial success handling). However, it omits mutation semantics (permissions required, thread vs individual message behavior) that would be critical for a write 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?
Uses a clean docstring structure with Args and Returns sections. Every sentence earns its place: the first line establishes the core operation and sibling distinction, Args documents the single parameter, and Returns documents the output structure. No redundancy or boilerplate.
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?
For a single-parameter tool with zero schema coverage, the description adequately fills gaps by documenting the parameter (Args) and return values (Returns). Given the output schema exists (per context signals), the Returns section may be partially redundant, but still provides semantic field descriptions. Completeness is appropriate for the tool's simplicity.
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%, requiring the description to compensate. The Args section successfully defines 'message_ids' as 'List of message IDs to mark as read', adding essential semantic context (the IDs represent messages) and purpose (to mark as read) that the bare JSON schema lacks. It loses a point for not specifying ID format or constraints.
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 opening line 'Mark emails as read without archiving' provides a specific verb (Mark), resource (emails), and target state (as read). Crucially, it explicitly distinguishes itself from the 'archive' sibling tool by stating the negative constraint 'without archiving', preventing confusion between the two mutation operations.
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 phrase 'without archiving' implicitly provides usage guidance by contrasting with the sibling 'archive' tool, indicating when to use this (when you want to keep the email in the inbox but mark it read). While it lacks exhaustive when-to-use logic for all siblings (like search vs mark), it successfully handles the most critical adjacent alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search emails using Gmail query syntax.
Args: query: Gmail search query (e.g., "from:user@example.com is:unread", "subject:invoice", "newer_than:1d"). max_results: Maximum number of results (1-100). Default: 20.
Returns: List of email objects matching the query.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| max_results | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full disclosure burden. It states the return type ('List of email objects'), but omits critical behavioral traits like read-only status (implicit but unconfirmed), rate limits, or result sorting order.
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 Args/Returns structure is clear and scannable. While embedding parameter documentation in the description text is redundant when schemas exist, it is necessary here given the schema lacks descriptions. No extraneous content.
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?
Adequate for a 2-parameter search tool with output schema present. Covers inputs and basic return structure, but gaps remain regarding safety profile (read-only assurance) and differentiation from the specialized 'list_unread' sibling.
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?
Excellent compensation for 0% schema coverage. The Args section fully documents both parameters: 'query' includes three concrete syntax examples, and 'max_results' specifies the valid range (1-100) and default value (20) absent from the schema.
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 identifies the action (search), resource (emails), and specific mechanism (Gmail query syntax). Examples like 'is:unread' and 'subject:invoice' implicitly distinguish it from sibling 'list_unread', though it could explicitly mention when to prefer the dedicated unread tool.
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 provides rich query syntax examples that implicitly guide usage, but lacks explicit guidance on when to use this versus siblings like 'list_unread' or prerequisites like authentication requirements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a distinct and clear purpose: archive emails, get labels, list unread emails, mark emails as read, and search emails. There is no overlap in functionality, making it easy for an agent to select the correct tool without confusion.
All tool names follow a consistent verb_noun pattern (e.g., archive, get_labels, list_unread, mark_as_read, search). The naming is straightforward and predictable, enhancing usability and clarity.
With 5 tools, the server is well-scoped for basic Gmail operations, covering key actions like reading, archiving, and searching emails. However, it lacks some advanced features like sending or deleting emails, which slightly limits its completeness but keeps the count reasonable.
The tool set covers essential read and modify operations (list, search, mark as read, archive) and label management, but it has notable gaps: there are no tools for sending emails, deleting emails, or managing drafts. This could lead to agent failures for common email workflows like composing or removing messages.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Read, search, send, organize, draft and schedule email across your inboxes from any MCP client.
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
A MCP server for Gmail that lets you search, read, and draft emails and replies.
Manage Gmail end-to-end: search, read, send, draft, label, and organize threads. Automate workflow…
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/fred-drake/gmail-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
