Gmail

Gmail

This connector reads, organises and writes the signed-in user's Gmail mailbox through the Gmail API v1 (https://gmail.googleapis.com/gmail/v1/users/me). It works with personal Gmail accounts and with Google Workspace mailboxes. Everything runs as the Google account that authorized the connector: the AI sees exactly what that account can see.

Setup (one-time, about 10 minutes)

1. Open https://console.cloud.google.com, pick or create a project, then APIs & Services → Library → enable Gmail API.
2. APIs & Services → OAuth consent screen: choose Internal if the mailbox is on Google Workspace (simplest, see Google verification below), otherwise External. For External, set the publishing status to In production: while an app is in Testing, Google revokes its refresh tokens after 7 days and the connector stops working every week.
3. APIs & Services → Credentials → Create credentials → OAuth client ID → application type Web application → add the authorized redirect URI <your AnythingMCP URL>/api/mcp-oauth/callback (on AnythingMCP Cloud: https://cloud.anythingmcp.com/api/mcp-oauth/callback).
4. Paste the client ID and secret into GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET and install the connector.
5. On the connector page, click Authorize with Provider and sign in with the Gmail account the AI should work with. The refresh token is stored encrypted and access tokens are renewed automatically.

Google verification (restricted scopes): Google classifies gmail.modify and gmail.readonly as restricted scopes. An External app that other people use needs Google's OAuth app verification, which for restricted scopes includes a security assessment; until then Google shows a "Google hasn't verified this app" warning and caps the app at 100 users. An Internal app, used only by accounts of the Google Workspace organisation that owns the Cloud project, needs no verification: it is the straightforward route for a company. For a single personal Gmail account, an External app In production that only you use works after you continue past the warning.

Scope: the connector asks for https://www.googleapis.com/auth/gmail.modify: read mail, change labels (mark read, archive, star), create drafts and send mail. It cannot permanently delete anything. For a read-only setup, change the scope to https://www.googleapis.com/auth/gmail.readonly in the connector's OAuth settings, authorize again, and disable gmail_modify_message_labels, gmail_modify_thread_labels, gmail_create_draft, gmail_send_draft, gmail_send_message and gmail_reply.

Finding mail: gmail_list_messages and gmail_list_threads take q in the same syntax as the Gmail search box, e.g. from:[email protected], is:unread, newer_than:7d, after:2026/10/01 before:2026/10/08, has:attachment, subject:offer, label:invoices, in:inbox, -category:promotions. They return ids only (messages: id and threadId; threads: id, snippet, historyId); fetch the content with gmail_get_message or gmail_get_thread. label_ids filters on labels that must all be present.

Reading a message

• gmail_get_message, gmail_get_thread and gmail_get_draft return each message decoded: from, to, cc, replyTo, subject, date, messageId, inReplyTo, references, labelIds, snippet, and text, the body as plain text (the text/plain part when there is one, otherwise the HTML part converted to text; textFormat says which). A very long body is cut at 20,000 characters (100,000 across a thread) and then carries textTruncated: true and the full textLength.
• Attachments are listed under attachments with filename, mimeType, size and attachmentId; this connector does not download them.
• format: "metadata" with metadata_headers (e.g. ["From", "To", "Subject", "Date"]) returns those headers, labels and snippet without the body. It is the cheapest way to triage many messages.
• format: "minimal" returns only ids and labels; raw returns the whole message as one base64url string, undecoded, and is rarely useful here.

Labels: system labels have fixed ids: INBOX, UNREAD, STARRED, IMPORTANT, SENT, DRAFT, SPAM, TRASH, CATEGORY_PERSONAL, CATEGORY_SOCIAL, CATEGORY_PROMOTIONS, CATEGORY_UPDATES, CATEGORY_FORUMS. User labels have ids such as Label_12: take them from gmail_list_labels, not from the label name. gmail_get_label adds the message and unread counts. With gmail_modify_message_labels / gmail_modify_thread_labels: mark as read = remove UNREAD; mark as unread = add UNREAD; archive = remove INBOX; star = add STARRED; file = add the label id (and remove INBOX to move it out of the inbox). Up to 100 label ids per call.

Writing mail

• gmail_send_message writes and sends a new email at once. gmail_create_draft saves the same kind of message as a draft instead, for the user to check in Gmail; gmail_send_draft later sends a draft exactly as it is, Gmail then removes the draft and the message gets the SENT label. When the user has not clearly asked to send, prefer a draft.
• Recipients (to, cc, bcc) are lists of addresses, each [email protected] or Ana Müller <[email protected]>. Subjects and names may use any language and emoji; the connector encodes them for mail headers. body is plain text with line breaks; html_body optionally adds an HTML version that mail clients show instead.
• Replying: read the message first with gmail_get_message (or the last message of gmail_get_thread), then call gmail_reply with its threadId as thread_id, its messageId as in_reply_to, its references (when present) as references, its subject as subject ("Re: " is added when missing) and its replyTo, or else from, as to. For reply-all, add the other to and cc addresses, except the user's own, to cc. Without thread_id and in_reply_to Gmail starts a new conversation. A reply draft is gmail_create_draft with the same thread_id, in_reply_to, references and a Re: subject.
• Sending cannot be undone. Gmail sends from the signed-in address and adds Date and Message-ID itself.

Pagination: list responses carry nextPageToken while more results exist; call the same tool again with the same arguments and page_token set to it. max_results goes up to 500 (default 100). resultSizeEstimate is an estimate, not an exact count.

Rate limits: Gmail meters quota units: 6,000 per minute per user and 1,200,000 per minute per project. A list costs 5 units, gmail_get_message 20, gmail_get_thread 40, a label change 5 (10 on a thread), creating a draft 10, sending a message or a draft 100, the profile and labels 1. Over the limit Gmail answers 429 (or 403 userRateLimitExceeded): wait a minute and retry. One message reaches at most 500 recipients.

Common errors

• 401: the authorization expired or was revoked (always after 7 days while the consent screen is in Testing). Click Authorize with Provider again.
• 403 insufficientPermissions / ACCESS_TOKEN_SCOPE_INSUFFICIENT: the scope does not allow the call, e.g. a label change on a read-only setup. 403 accessNotConfigured / "Gmail API has not been used in project": enable the Gmail API in the Cloud project (step 1).
• 404: the id does not exist in this mailbox, or the message was deleted. A draft id (r-…) is not a message id.
• 400 invalidArgument: a label id that does not exist, or an invalid query parameter. 400 "Recipient address required": gmail_send_message or gmail_reply without a to.
• An error about an e-mail address, a Message-ID or a line break comes from the connector before anything is sent: fix the argument it names.

Out of scope here: sending or downloading attachments, forwarding with the original attachments, trash and deletion, filters, settings, send-as aliases, other users' mailboxes.