Provides tools for searching emails, retrieving content, managing labels, sending and forwarding emails, and batch operations on Gmail accounts via IMAP and SMTP.
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 List my most recent emails in inbox"
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.
This project implements a Model Context Protocol (MCP) server that allows interaction with Gmail accounts via IMAP and SMTP. It provides tools for searching emails, retrieving content, managing labels (creating, deleting, renaming, applying, removing), and sending/forwarding emails.
Email Search: Search emails by date range, keyword, or raw Gmail query string. Supports searching specific folders (inbox, sent) and limiting results. Uses Gmail's X-GM-RAW extension for efficient inbox searching (e.g., filtering by category:primary).
Email Content Retrieval: Fetch the full content (headers, body, attachments) of a specific email using its sequence ID.
Label Management (CRUD):
List all available Gmail labels (folders).
Create new custom labels.
Rename existing custom labels.
Delete existing custom labels (cannot delete system labels).
Apply labels to individual emails.
Remove labels from individual emails.
Batch Operations:
Apply labels to multiple emails simultaneously using sequence IDs.
Remove labels from multiple emails simultaneously.
Move multiple emails to a specific label/folder.
Email Sending: Send new emails (requires SMTP configuration).
Email Forwarding: Forward existing emails, including attachments (requires SMTP configuration).
Daily Email Count: Count emails received per day within a specified date range.
Related MCP server: mcp-gmail
.
├── .gitignore # Specifies intentionally untracked files that Git should ignore
├── .python-version # Specifies Python version (used by pyenv)
├── LICENSE # Project license file
├── pyproject.toml # Python project configuration (dependencies, build system)
├── README.md # This file
├── task_list.md # Tracks development progress
├── uv.lock # Lock file for uv package manager
├── src/
│ └── email_client/
│ ├── __init__.py
│ ├── config.py # Handles loading configuration from environment variables (.env)
│ ├── handlers.py # Implements the logic for handling MCP tool calls
│ ├── imap_client.py # Contains functions for interacting with IMAP server
│ ├── server.py # Main MCP server script using @modelcontextprotocol/sdk
│ ├── smtp_client.py # Contains functions for interacting with SMTP server
│ ├── tool_definitions.py # Defines the available MCP tools and their schemas
│ └── utils.py # Utility functions (e.g., email parsing, date formatting)
└── ... (other potential files like test scripts, helper scripts)Clone the repository (if applicable):
git clone https://github.com/david-strejc/gmail-mcp-server.git
cd gmail-mcp-serverInstall Dependencies: This project uses uv for package management.
# Ensure uv is installed (e.g., pip install uv)
uv venv # Create virtual environment (.venv)
uv sync # Install dependencies from pyproject.toml and uv.lock
source .venv/bin/activate # Activate the virtual environment(Alternatively, if not using uv, create a virtual environment and install using pip install -r requirements.txt if a requirements.txt is generated).
Configure Environment Variables: Create a .env file in the project root directory and add your Gmail credentials and server settings:
# .env file
GMAIL_EMAIL=your_email@gmail.com
GMAIL_PASSWORD=your_app_password # Use an App Password if 2FA is enabled
GMAIL_IMAP_SERVER=imap.gmail.com
GMAIL_SMTP_SERVER=smtp.gmail.com
GMAIL_SMTP_PORT=587 # Or 465 for SSLImportant: For Gmail, if you have 2-Factor Authentication enabled, you must generate and use an "App Password". Standard passwords will not work. See Google's documentation on App Passwords.
Ensure "Less secure app access" is enabled if you are not using 2FA (this is generally discouraged).
Activate the virtual environment and run the server script:
source .venv/bin/activate
python src/email_client/server.pyThe server will start and listen for MCP requests via standard input/output.
Add the server configuration to your MCP client's settings file (e.g., cline_mcp_settings.json or claude_desktop_config.json).
Example cline_mcp_settings.json entry:
{
"mcpServers": {
"gmail": {
"command": "/path/to/your/project/gmail-mcp-server/.venv/bin/python",
"args": ["/path/to/your/project/gmail-mcp-server/src/email_client/server.py"],
"env": {}, // Environment variables are loaded from .env by the script
"enabled": true, // Set to true to enable
"autoApprove": [] // Configure auto-approval if desired
}
// ... other servers
}
}Replace /path/to/your/project/gmail-mcp-server with the actual absolute path to this project directory.
Ensure the command points to the python executable within the project's virtual environment (.venv/bin/python).
Once configured and enabled, the client should connect to the server, and the defined tools will become available.
search-emails: Search emails.
get-email-content: Get full email details.
count-daily-emails: Count emails per day.
list-labels: List all labels/folders.
create-label: Create a new label.
rename-label: Rename an existing label.
delete-label: Delete a label.
apply-label: Apply a label to one email.
remove-label: Remove a label from one email.
apply-label-batch: Apply a label to multiple emails.
remove-label-batch: Remove a label from multiple emails.
move-email: Move a single email to a label.
move-email-batch: Move multiple emails to a label.
send-email: Send a new email.
forward-email: Forward an existing email.
Refer to src/email_client/tool_definitions.py for detailed input schemas for each tool.
Apply a label to an email
| Name | Required | Description | Default |
|---|---|---|---|
| email_id | Yes | The ID of the email to label | |
| label_name | Yes | Name of the label to apply |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description fails to disclose critical behavioral traits such as whether the label must already exist, if the operation is idempotent, or what side effects occur (e.g., replacing existing labels).
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 extremely concise (one sentence) with no wasted words. However, it could be slightly more structured by including a brief note on usage.
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 the lack of output schema and annotations, the description is too sparse. It does not cover preconditions, error behavior, or return values, leaving the agent with insufficient context for safe usage.
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 100%, so baseline is 3. The description adds no additional meaning beyond the parameter names and schema descriptions; it merely restates them.
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 action (apply) and the resource (label to email), and it distinguishes from sibling tools like apply-label-batch and remove-label.
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 use this tool versus the batch variant or prerequisites like label existence. The description is minimal and offers no usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply a label to multiple emails using their sequence IDs (from search results)
| Name | Required | Description | Default |
|---|---|---|---|
| email_ids | Yes | List of email sequence IDs to label | |
| label_name | Yes | Name of the label to apply |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and description lacks disclosure of behavioral traits (e.g., mutation, error handling, idempotency). Only states basic function.
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?
Single sentence, front-loaded with action and resource, 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?
No output schema, no annotations; description does not cover return values, error cases, or prerequisites, making it incomplete for safe agent use.
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 context that email_ids are sequence IDs from search results, augmenting the schema descriptions which already cover 100% of parameters.
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?
Description clearly states the action (apply label) and resource (multiple emails), and distinguishes from siblings like 'apply-label' (single email) and 'remove-label-batch'.
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?
Hints at usage after a search ('from search results'), but no explicit when-to-use or alternatives; naming partially distinguishes batch vs. single.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Count emails received for each day in a date range
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | Yes | Start date in YYYY-MM-DD format | |
| end_date | Yes | End date in YYYY-MM-DD format |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description carries full burden. It does not disclose scope (e.g., all folders, spam), side effects, rate limits, or output format. Minimal behavioral context beyond the basic 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?
Single sentence, zero waste, front-loaded with verb and resource.
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?
Missing output format (array of date-count objects), scope (which mailbox), and assumptions about missing days. No output schema to compensate.
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 100%, so baseline is 3. Description adds no extra meaning beyond schema; it implies date range but doesn't clarify inclusive/exclusive bounds or format validation.
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 'Count emails received for each day in a date range' uses a specific verb ('count') and resource ('emails') and clearly distinguishes from sibling tools like 'search-emails' or '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?
No guidance on when to use this tool versus alternatives. It does not mention when not to use it or compare to other tools like 'search-emails' for broader queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new Gmail label/folder
| Name | Required | Description | Default |
|---|---|---|---|
| label_name | Yes | Name of the label to create |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits but only says 'Create a new Gmail label/folder'. It omits side effects, visibility, permissions, or constraints.
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?
Very concise (one phrase), but underspecified for a minimal viable description. Not verbose, but lacks structure.
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 the simple tool, the description should mention constraints or response behavior. It is incomplete for an agent to confidently invoke.
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 100% and parameter is self-explanatory, but description adds no extra context (e.g., naming rules, examples). Baseline 3 is appropriate.
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 action ('Create') and the resource ('new Gmail label/folder'), distinguishing it from sibling tools like delete-label or rename-label.
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 use this tool vs alternatives (e.g., rename-label or delete-label). Lacks context about prerequisites or limitations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a Gmail label/folder entirely. Cannot delete system labels.
| Name | Required | Description | Default |
|---|---|---|---|
| label_name | Yes | Name of the label/folder to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that deletion is 'entirely' (destructive) and that system labels are protected. However, it does not detail consequences for emails associated with the label, any confirmation steps, or reversibility. Some behavioral gaps remain.
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 extremely concise with two sentences. The first sentence states the action directly, and the second adds a key constraint. No unnecessary words or 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 the tool's simplicity (1 parameter, no output schema), the description covers the core purpose and a major constraint. However, it omits details about prerequisites (e.g., permissions) and what happens to associated emails, leaving the agent with moderate uncertainty.
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?
The input schema provides a clear description for 'label_name' ('Name of the label/folder to delete'), achieving 100% coverage. The tool description adds value by stating that system labels cannot be deleted, which constrains valid parameter values beyond 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 states the action: 'Delete a Gmail label/folder entirely.' It uses a specific verb and resource, and distinguishes from sibling tools like 'rename-label' or 'create-label' by focusing on deletion. The additional constraint 'Cannot delete system labels' further clarifies scope.
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 does not provide explicit guidance on when to use this tool versus alternatives (e.g., 'remove-label' which removes a label from an email). It implies usage for permanently deleting user-created labels, but lacks direct comparison or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Forward an email with its attachments to new recipients. Required fields: email_id and recipients (to). Optional: subject_prefix, additional_message, and CC recipients.
| Name | Required | Description | Default |
|---|---|---|---|
| email_id | Yes | The ID of the email to forward | |
| to | Yes | List of recipient email addresses | |
| subject_prefix | No | Prefix to add to the original subject (default: 'Fwd: ') | Fwd: |
| additional_message | No | Optional message to add before the forwarded content | |
| cc | No | List of CC recipient email addresses (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only states the action without disclosing behavioral traits such as whether it modifies the original, required permissions, or rate limits.
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?
Single sentence with front-loaded action and clear identification of required vs optional fields, containing 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?
For a simple forwarding tool with no output schema, the description covers the essential action and parameters, though it lacks mention of side effects or prerequisites.
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?
The input schema has 100% parameter descriptions, so the description adds no new semantic value beyond listing optional fields already covered by 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 uses a specific verb 'Forward' and resource 'an email with its attachments', clearly distinguishing it from siblings like send-email (compose new), move-email (change folder), and apply-label (add labels).
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 use when forwarding an existing email but does not explicitly state when to use siblings or exclude cases, leaving the agent to infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the full content of a specific email by its ID
| Name | Required | Description | Default |
|---|---|---|---|
| email_id | Yes | The ID of the email to retrieve |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must carry the full burden. It says 'full content' but does not specify whether that includes attachments, headers, or metadata. No mention of permissions, rate limits, or destructive potential.
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 a single, clear sentence with no redundant words. It is front-loaded with the action and resource.
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 the low complexity (1 parameter, no output schema), the description is minimally adequate but lacks details on what 'full content' includes. It does not compensate for the missing output schema.
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 100% and the description adds no additional meaning beyond what the schema already provides for email_id. It does not specify the format or source of the ID.
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 action (Get), resource (full content of an email), and the identifier (by its ID). It distinguishes from siblings like search-emails (which lists) and forward-email (which sends).
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 use this tool versus alternatives, such as after using search-emails to find an email ID, or what prerequisites exist (e.g., email must exist).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available Gmail labels/folders
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It states it lists all labels, but fails to disclose authentication needs, rate limits, or return format. The simplicity partially compensates.
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?
A single, well-structured sentence that is front-loaded and to the point with no extraneous 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 zero parameters and no output schema, the description adequately covers the tool's basic purpose. However, it could benefit from mentioning what is returned (e.g., list of label IDs and names).
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 has no parameters, and schema description coverage is 100%. The description adds no extra param info, which is acceptable since none exist.
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 uses specific verb 'List' and resource 'Gmail labels/folders', clearly distinguishing it from sibling tools like create-label, delete-label, rename-label.
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 use this tool vs alternatives (e.g., when to list labels vs apply or search). No context or exclusions provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move an email to a specific folder/label
| Name | Required | Description | Default |
|---|---|---|---|
| email_id | Yes | The ID of the email to move | |
| destination_label | Yes | Name of the destination folder/label |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose behavioral details such as whether moving removes from previous folder, required permissions, or side effects. The description carries the full burden but lacks sufficient transparency.
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?
One short sentence efficiently conveys the core purpose with no wasted words. However, it could benefit from slight elaboration on usage or behavior.
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?
The description provides the essential purpose for a simple tool with no output schema, but lacks behavioral and usage context that would make it fully 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 coverage is 100%, so the schema already describes both parameters adequately. The description adds no extra meaning beyond what the schema provides, meeting the baseline expectation.
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 states the action (Move) and the resource (email to a specific folder/label), clearly distinguishing from siblings like 'apply-label' (which applies a label without moving) and 'move-email-batch' (batch version).
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 use this tool versus alternatives such as 'apply-label' or 'move-email-batch'. The description fails to provide context for choosing this tool over siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move multiple emails to a specific folder/label using their sequence IDs (from search results)
| Name | Required | Description | Default |
|---|---|---|---|
| email_ids | Yes | List of email sequence IDs to move | |
| destination_label | Yes | Name of the destination folder/label |
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 the tool moves emails using sequence IDs, but does not specify behavioral traits such as whether the operation is destructive, permission requirements, batch limits, or return behavior. This is insufficient for a batch mutation tool.
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 a single sentence (16 words) that front-loads the core action and target. No redundant information. Highly efficient.
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 the absence of an output schema and the nature of a batch operation, the description should explain return values, success/failure indicators, and potential limitations (e.g., max batch size). None of this is provided, leaving the agent without critical information.
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 100% with both parameters described. The description adds minor context by specifying that IDs come from search results, which is slightly helpful beyond the schema. Baseline 3 is appropriate.
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 action ('move multiple emails'), target ('to a specific folder/label'), and method ('using their sequence IDs from search results'). It distinguishes itself from sibling tools like 'move-email' (single) and 'apply-label-batch' (apply vs move).
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 when the agent has multiple email sequence IDs from search results, but does not explicitly state when to use this tool over alternatives like 'move-email' (single) or 'apply-label-batch' (different operation). No exclusions or conditions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a label from an email
| Name | Required | Description | Default |
|---|---|---|---|
| email_id | Yes | The ID of the email to remove the label from | |
| label_name | Yes | Name of the label to remove |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It states the operation but does not disclose whether the label must exist, if changes are immediate, or any error conditions beyond basic semantics.
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?
One short sentence with no extraneous information; highly concise and front-loaded.
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 simple tool with no annotations and two well-described parameters, the description is adequate but could provide more context about prerequisites or side effects.
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 100% with both parameters described. The description adds no extra meaning beyond the schema, so baseline 3 is appropriate.
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 action 'Remove' and the resource 'label from an email', distinguishing it from sibling tools like 'apply-label' (add) and 'remove-label-batch' (batch removal).
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 use this tool versus alternatives; does not mention that 'remove-label-batch' exists for batch operations or that 'apply-label' is for adding labels.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a label from multiple emails using their sequence IDs (from search results)
| Name | Required | Description | Default |
|---|---|---|---|
| email_ids | Yes | List of email sequence IDs to remove the label from | |
| label_name | Yes | Name of the label to remove |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits beyond the basic action. Missing details on side effects, permissions, error handling (e.g., if label not found or some emails fail), or limitations (e.g., batch size). For a mutating batch operation, this is insufficient.
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 a single, efficient sentence with no filler. It is front-loaded and directly conveys the core action and input type.
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 the lack of annotations and output schema, the description is adequate for a simple tool but missing important context for a batch operation. No mention of error handling, partial failures, or performance considerations. Leaves the agent without guidance on edge cases.
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 100% with basic descriptions for both parameters. The description adds context by specifying that email_ids are 'sequence IDs (from search results)', which clarifies the expected source. However, no additional format or constraints are provided.
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 action ('remove a label') from multiple emails, specifies the input ('sequence IDs from search results'), and distinguishes from siblings like 'remove-label' (singular) and 'apply-label-batch' (opposite).
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 explicit guidance on when to use vs alternatives like 'remove-label' (for single email) or 'apply-label-batch' (for adding). Usage is implied by the name and description, but no when-not or alternative recommendations are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rename an existing Gmail label/folder. Cannot rename system labels.
| Name | Required | Description | Default |
|---|---|---|---|
| old_label_name | Yes | Current name of the label/folder to rename | |
| new_label_name | Yes | New name for the label/folder |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full burden. It discloses the rename action and a constraint (system labels), but fails to mention side effects, idempotency, required permissions, or any output behavior, which is insufficient for a mutation tool.
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?
Single, front-loaded sentence with no wasted words. Every part of the description adds value.
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 simple rename tool with no output schema and no annotations, the description covers purpose and a constraint, but lacks details on return values, confirmation, prerequisites, or behavioral traits. It meets minimum viability but leaves gaps.
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 100% (both parameters described in schema). The description adds the constraint about system labels, which provides additional context for parameter usage beyond 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?
Description clearly states 'Rename an existing Gmail label/folder' with a specific verb and resource, and explicitly notes the tool cannot rename system labels, distinguishing it from sibling tools like create-label and delete-label.
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?
Description implies usage for renaming labels, and the constraint 'Cannot rename system labels' provides a context-based exclusion. However, it lacks explicit guidance on when not to use or mention of alternative tools for related operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search emails within a date range and/or with specific keywords
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | No | Start date in YYYY-MM-DD format (optional) | |
| end_date | No | End date in YYYY-MM-DD format (optional) | |
| keyword | No | Keyword to search in email subject and body (optional). Ignored if raw_query is provided. | |
| raw_query | No | Gmail advanced search query string (e.g., 'has:attachment from:boss'). If provided, other search parameters (dates, keyword) are ignored. | |
| folder | No | Folder to search in ('inbox' or 'sent', defaults to 'inbox') | inbox |
| limit | No | Maximum number of emails to return (default: 20) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It does not mention pagination, default behavior when no parameters are provided, return format, performance implications, or permissions. The description is overly simplistic.
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?
A single, grammatically correct sentence with no wasted words. The core purpose is front-loaded and immediately understandable. However, it could benefit from brief structural elements like bullet points.
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?
Despite having 6 parameters and no output schema, the description does not explain what the output is (e.g., list of email IDs, summaries) or default behaviors (e.g., searching inbox by default). It is incomplete for a tool of this complexity.
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 100%, so the baseline is 3. The description adds minimal extra meaning by grouping 'date range' and 'keywords', but the individual parameter descriptions already convey the specifics. No value beyond 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 states the action ('Search'), the resource ('emails'), and the filtering criteria (date range and/or keywords). It is distinct from sibling tools like 'get-email-content' or 'count-daily-emails', though it does not explicitly highlight these distinctions.
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 use this tool versus alternative siblings or when to avoid it. The description only implies usage for filtering by dates or keywords, but does not provide explicit context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
CONFIRMATION STEP: Actually send the email after user confirms the details. Before calling this, first show the email details to the user for confirmation. Required fields: recipients (to), subject, and content. Optional: CC recipients.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | List of recipient email addresses (confirmed) | |
| subject | Yes | Confirmed email subject | |
| content | Yes | Confirmed email content | |
| cc | No | List of CC recipient email addresses (optional, confirmed) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool sends an email (destructive action) and labels it a 'CONFIRMATION STEP', implying it should only be called after user confirmation. However, it does not mention side effects (e.g., irreversible), required permissions, or error behavior. It provides minimal behavioral context beyond the action itself.
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 concise sentences with no waste. The first sentence front-loads the core purpose and usage guideline, making it immediately actionable. Every word earns its place.
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 there is no output schema and no annotations, the description provides minimal context. It covers the action and preconditions but omits return value (e.g., success confirmation), error handling, and irreversibility. For a send operation with 4 parameters, it is adequate but not comprehensive.
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 100% (all 4 parameters described in schema), so the baseline is 3. The description adds: 'Required fields: recipients (to), subject, and content. Optional: CC recipients.' This maps 'recipients' to the 'to' parameter but does not add new meaning beyond the schema's existing descriptions (e.g., 'List of recipient email addresses (confirmed)'). Thus, it barely enriches 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 the tool's purpose: 'Actually send the email after user confirms the details.' It uses a specific verb+resource (send email) and distinguishes from siblings by emphasizing it is a confirmation step. No other sibling tool sends an email, so differentiation is inherent.
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 explicitly states a precondition: 'Before calling this, first show the email details to the user for confirmation.' It also lists required and optional fields. However, it does not mention when not to use the tool or provide alternatives, but given the sibling list, no alternatives exist, so the guidance is clear.
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 clearly distinct purpose: individual vs batch operations are separated, and all actions (apply label, remove label, move, etc.) target different aspects of Gmail management. No overlap that would cause confusion.
Tool names follow a consistent verb_noun pattern (e.g., apply-label, create-label, search-emails). Batch variants include '-batch' suffix, and 'count-daily-emails' is the only slight deviation but still clear. Overall predictable and uniform.
With 15 tools covering email search, retrieval, sending, forwarding, label management (CRUD plus batch operations), and counting, the scope is well-balanced for a Gmail server. Each tool serves a distinct purpose and the count feels right.
The tool set covers core operations like sending, forwarding, searching, and label management, but lacks common email actions such as marking as read/unread, trashing, archiving, or managing drafts. Batch operations are a plus, but some expected Gmail features are missing.
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.
Email inboxes for AI agents: send, receive, reply, search, and manage threaded email over MCP.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/david-strejc/gmail-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
