Gmail no-CASA MCP

Gmail no-CASA MCP

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/[email protected] MIT-licensed release candidate. It is prepared for local packing and installed-artifact validation, but it has not been published or enabled in production.

V1 surface

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.

Tool contract

send_email

Input:

{
  "to": ["[email protected]"],
  "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.

Label tools

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:

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.

Authentication and runtime

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 --version

Running 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.

Host safety limitations

The package cannot control host approval grants or workflow replay. Before enabling send_email, the integrating host must provide both guarantees:

1. 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.
2. 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.

Validation

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=dev

npm 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.tgz

Release gates

The intended release lineage is a reviewed source revision → @enterpret/[email protected] → 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.

References

• Gmail OAuth scopes
• Gmail users.messages.send
• Gmail users.labels