Allows sending plain-text emails and managing Gmail user labels (create, update, delete) through MCP tools, using only Gmail's send and labels OAuth scopes.
Click on "Deploy 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 no-CASA MCP Send email to alice@example.com: subject 'Meeting' body 'See you'"
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.
First-party, minimal Gmail MCP for explicitly approved plain-text sending and Gmail user-label object management over stdio, using only Gmail's send and labels OAuth scopes.
Maintained by Enterpret as the Gmail integration for the Enterpret Agent. Its standards-based MCP interface can also be used by compatible hosts that meet the approval and replay-safety requirements documented below.
This repository contains the @enterpret/gmail-mcp@0.1.0 MIT-licensed release candidate. It is prepared for local packing and installed-artifact validation, but it has not been published or enabled in production.
The MCP registers exactly four tools:
send_email
create_label
update_label
delete_label
The integration requests exactly two scopes:
https://www.googleapis.com/auth/gmail.send
https://www.googleapis.com/auth/gmail.labels
No message, thread, inbox, or search reads are exposed. V1 also excludes drafts, replies, forwarding, attachments, HTML, raw MIME, sender aliases, message labeling, archive/trash/star/read mutations, synchronization, triggers, HTTP MCP transport, and unrelated Workspace services.
As of July 2026, Google classifies gmail.labels as non-sensitive and gmail.send as sensitive; neither scope is restricted. The sensitive send scope still requires the applicable OAuth app verification for broad external production, but this exact scope set does not invoke the restricted-scope security assessment/CASA path. Do not broaden the scopes without a new product and security review.
Related MCP server: Gmail Local MCP
send_emailInput:
{
"to": ["alice@example.com"],
"cc": [],
"bcc": [],
"subject": "Exact subject",
"body": "Complete plain-text body"
}All five fields are required so the approval surface has an explicit value for every recipient group, subject, and body. Recipient arrays accept bare ASCII mailbox addresses only; display names and surrounding whitespace are rejected. There must be at least one to recipient, no exact duplicate across recipient fields, and at most 100 total recipients. Subjects are limited to 200 characters and reject CR, LF, and NUL. Bodies are limited to 100,000 characters and reject NUL.
The parser preserves the approved values exactly. The transport independently builds RFC-compatible plain-text MIME with deterministic address and encoded-subject folding, an internally generated UTC Date header, UTF-8/base64 body encoding, and Gmail base64url encoding. It never adds From, Reply-To, or Message-Id. Gmail binds the OAuth-authenticated account's configured default sender; this is not necessarily the primary login address.
Success is deliberately minimal:
{ "status": "sent" }The package performs one provider dispatch attempt. A connection failure, lost response, or HTTP 5xx after dispatch begins returns send_unknown_outcome, outcome: "unknown", and retryable: false. The package never treats that as permission to resend and never exposes Gmail response bodies or provider message IDs.
Labels use exact, case-sensitive user-label names as public identity. Nested names such as Projects/Launch are accepted. Names are limited to 200 characters and reject control characters and leading or trailing whitespace. Provider IDs are internal and never appear in schemas or results.
create_label takes name, optional label_list_visibility (labelShow, labelShowIfUnread, or labelHide), and optional message_list_visibility (show or hide). Defaults are labelShow and show.
update_label takes the exact current name plus at least one of new_name, label_list_visibility, or message_list_visibility.
delete_label takes the exact name.
Internal label resolution calls Gmail's labels list endpoint, compares exact names, and accepts only the provider's lowercase type: "user". Lowercase type: "system" is rejected, including rename targets; uppercase variants are treated as invalid provider responses. Duplicate exact names are an error rather than an arbitrary choice. Result objects return only status, name, and relevant visibility—not provider IDs, counts, or mailbox metadata.
Tool annotations are fixed as follows:
Tool |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Sending is irreversible and non-idempotent, but additive rather than destructive under the MCP annotation definition. Safety must come from trusted host policy, not an inflated destructiveHint. All label idempotence hints remain false because exact-name resolution does not make ambiguous create, rename, update, or delete replay safe.
The server uses MCP over stdio only. It reads one fresh access token from GMAIL_OAUTH_BEARER at startup. Missing, blank, or whitespace-only values fail closed before the server becomes usable.
The package contains no OAuth UI, access-token refresh, refresh-token handling, token persistence, credential files, filesystem state, or HTTP transport. It reserves stdout for JSON-RPC and emits only fixed, sanitized diagnostics to stderr. Errors expose a stable category, outcome, non-retryable flag, and safe HTTP status when available; they omit authorization headers, tokens, recipients, subjects, bodies, raw MIME, and provider error bodies.
OAuth authorization, refresh-token custody, access-token refresh, and persistence belong to the integrating host or its token broker. The host injects only a fresh bearer into a fresh MCP child. Deployments should pin an exact immutable package version when invoking through npx; preinstalling and directly executing the reviewed package keeps bearer material out of package-install processes.
Build and inspect the local binary with Node 22 or later:
npm ci
npm run check
node dist/index.js --versionRunning the server without GMAIL_OAUTH_BEARER must exit nonzero. Do not store a live bearer in this repository, an .env file, shell history, fixtures, or logs.
The package cannot control host approval grants or workflow replay. Before enabling send_email, the integrating host must provide both guarantees:
Every send_email call receives fresh explicit user approval, even after an earlier “always allow” choice or in high-autonomy mode. Approval must display the exact to, cc, bcc, subject, and complete body without truncation.
Once a send may have reached Gmail, timeout, process failure, connection close, saved-grant reuse, and workflow replay cannot dispatch it again. The result remains unknown until the user independently verifies delivery.
delete_label must also receive consequence-aware approval explaining that deleting a Gmail user label removes that label from all affected messages and threads. Create and update use the host's normal write approval unless a stricter policy is adopted.
Credential-free tests cover the exact MCP surface and annotations, bearer failure, schemas and negative features, approval-payload fidelity, MIME/base64url/Unicode behavior, mocked send and label endpoints, lowercase provider label types, system-label rejection, redaction, and ambiguous-send single-attempt behavior.
Before any release candidate:
npm ci
npm run check
npm pack --dry-run
npm audit --omit=devnpm run smoke:pack builds a fresh tarball in a temporary directory and runs MCP initialization plus exact four-tool discovery through npx -y against that artifact. CI runs the same command on every push and pull request.
Also inspect the packed files, install the reviewed tarball into a fresh temporary consumer, smoke-test the installed CLI and stdio initialization/tool discovery, and scan the source and package for credentials and scopes. Live Gmail calls, real sends, OAuth-provider configuration, host-integration changes, commits, remotes, publication, and production enablement require separate authorization.
The packed-artifact discovery smoke accepts the tarball produced by npm pack and executes that exact artifact through npx without making a Gmail API call:
node scripts/packed-npx-smoke.mjs /path/to/enterpret-gmail-mcp-0.1.0.tgzThe intended release lineage is a reviewed source revision → @enterpret/gmail-mcp@0.1.0 → an exact deployment pin. Repository readiness, npm publication, OAuth configuration, host safety policy, integration testing, and production enablement are independent gates. Google's sensitive-scope verification is required for broad external production use of gmail.send.
See THIRD_PARTY_NOTICES.md for provenance. No source from the upstream reference implementations was copied or adapted.
Repository and npm publication procedures are documented in RELEASING.md. Publishing remains an explicit, separately authorized action.
Create one Gmail user label by exact name. This is an external write; it does not apply the label to messages or threads.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Exact Gmail user-label name. | |
| label_list_visibility | No | labelShow | |
| message_list_visibility | No | show |
| Name | Required | Description |
|---|---|---|
| label | Yes | |
| status | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read/write nature (readOnlyHint=false) and non-destructive (destructiveHint=false). Description adds 'external write' context beyond annotations, but lacks details on error handling, duplicate behavior, or side effects.
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 core purpose, no unnecessary words. Every sentence 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?
Covers essential context (Gmail, exact name, external write, scope). Output schema handles return values. Missing error conditions or duplicate handling, but acceptable for a simple creation tool.
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 33% (only 'name' described). Description adds no additional meaning for 'label_list_visibility' or 'message_list_visibility' parameters, failing to compensate for low coverage.
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?
Clearly states verb (create), resource (Gmail user label), and scope (exact name, external write, does not apply to messages). Clearly distinguishes from siblings (delete_label, update_label, 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?
Explicitly states what the tool does and does not do (does not apply label to messages). Provides clear context for when to use, but no explicit when-not-to or alternatives mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete one Gmail user label resolved by exact name. Deleting the label removes it from every affected message and thread, so the host must obtain explicit consequence-aware approval.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Exact Gmail user-label name to delete. |
| Name | Required | Description |
|---|---|---|
| label | Yes | |
| status | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true and readOnlyHint=false. The description adds crucial details: 'permanently delete', 'removes from every affected message and thread', and the requirement for explicit consequence-aware approval, going well beyond the annotations.
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 with no wasted words. First sentence states purpose and method; second explains consequences and approval requirement. Perfectly 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?
Given the tool's simplicity (one parameter, destructive, with output schema), the description covers purpose, behavior, parameter method, and approval requirement. No gaps noted.
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 parameter description already states 'Exact Gmail user-label name to delete.' The description adds no additional semantics beyond what the schema provides, so baseline of 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 explicitly states 'permanently delete one Gmail user label resolved by exact name', clearly identifying the verb, resource, and method. It distinguishes itself from siblings (create_label, update_label, send_email) by focusing on deletion.
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 warns about the destructive nature ('removes from every affected message and thread') and instructs to obtain explicit approval. However, it does not explicitly state when to use this tool versus alternatives or provide when-not scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send one plain-text email from the connected Gmail account. The host must obtain fresh explicit approval for every call and show the exact to, cc, bcc, subject, and complete body. A response lost after dispatch has an unknown outcome and must never be retried automatically.
| Name | Required | Description | Default |
|---|---|---|---|
| cc | Yes | Exact ordered Cc recipients; use an empty array when absent. | |
| to | Yes | Exact ordered To recipients. | |
| bcc | Yes | Exact ordered Bcc recipients; use an empty array when absent. | |
| body | Yes | Complete plain-text body, preserved exactly. | |
| subject | Yes | Plain-text subject, preserved exactly. |
| Name | Required | Description |
|---|---|---|
| status | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses critical behavioral traits beyond annotations: need for explicit approval, exact content disclosure, unknown outcome on lost response, and prohibition on automatic retries. This aligns with openWorldHint=true and adds significant value.
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 concise with three sentences, front-loading the core purpose and then adding critical usage notes. Every sentence earns its place with no 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?
Given the tool's complexity (5 required params, mutation with side effects), the description covers the function, approval requirement, and retry prohibition. An output schema exists, so lack of return value description is acceptable.
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 does not add semantic details beyond referencing the fields, as the schema already provides constraints. No contradiction.
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 sends one plain-text email from the connected Gmail account, distinguishing it from sibling label management tools. The verb 'send' and resource 'email' are specific.
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 important usage constraints: host must obtain fresh approval and never auto-retry on lost response. While it does not explicitly compare to alternatives, the context is sufficient given sibling tools are unrelated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update one Gmail user label resolved by its exact current name. This can rename the label or change its Gmail visibility settings; it does not modify message membership.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Exact current Gmail user-label name. | |
| new_name | No | ||
| label_list_visibility | No | ||
| message_list_visibility | No |
| Name | Required | Description |
|---|---|---|
| label | Yes | |
| status | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive and non-read-only behavior. The description adds context that message membership is unaffected, which is a key behavioral detail beyond annotations. No contradictions detected.
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 pack the essential information: the action, the resource (exact current name), the scoped changes (rename/visibility), and a clear exclusion. No redundancy or fluff.
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 update tool, the description covers the main functionality and exclusions. An output schema exists (not shown), so return values are handled. Could mention authentication or label scope, but overall complete enough to use correctly.
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?
With only 25% schema description coverage, the description provides high-level context (e.g., 'rename the label or change its Gmail visibility settings') that maps to parameters like new_name and visibility enums. It partially compensates for the low coverage but does not detail each parameter's exact meaning.
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 'Update one Gmail user label' with the specific action of renaming or changing visibility. It distinguishes from sibling tools like create_label and delete_label by specifying what it does not do (modify message membership).
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 explains what the tool does and explicitly states what it does not modify, guiding the agent on appropriate use. However, it lacks direct comparison to siblings (e.g., when to use update vs create/delete) and does not mention prerequisites like authentication.
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.
v0.1.0create_labeldelete_labelsend_emailupdate_labelScored across 4 tools
Each tool targets a distinct action: create, delete, update labels, and send email. No overlap between label operations and email sending.
All tools follow a consistent verb_noun pattern using snake_case (e.g., create_label, send_email), making them predictable.
With 4 tools, the set is on the lower end but within the typical 3-15 range. More tools could be useful, but the count is not problematic.
The server lacks fundamental Gmail operations such as reading, searching, or listing emails, and label tools do not allow applying labels to messages, leaving significant gaps.
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.
MCP server for Nylas — read email, calendars, events and contacts, and send email or create events.
Streamable HTTP MCP server for Google Calendar and Sheets with OAuth login.
