Google Workspace MCP Server - Control Gmail, Calendar, Docs, Sheets, Slides, Chat, Forms & Drive

Draft Gmail Message

draft_gmail_message

Creates a Gmail draft for new or reply emails, with optional attachments, aliases, CC/BCC, and signatures—ready for review or sending.

Instructions

Creates a draft email in the user's Gmail account. Supports both new drafts and reply drafts with optional attachments. Supports Gmail's "Send As" feature to draft from configured alias addresses.

SCHEDULED SEND IS NOT AVAILABLE. Gmail's REST API exposes no send-time parameter; the Schedule send feature is web-UI only, and a message cannot be placed in the Scheduled folder through the API. Do not claim a message was scheduled. To deliver at a chosen time, create a draft with draft_gmail_message. An external scheduler must retain the message data to create and send a new message via send_gmail_message then, or call users.drafts.send with the draft ID returned by draft_gmail_message. Alternatively, let the user schedule the draft in the Gmail UI.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`cc`	No	Optional CC email address.
`to`	No	Optional recipient email address.
`bcc`	No	Optional BCC email address.
`body`	Yes	Email body (plain text).
`subject`	Yes	Email subject.
`from_name`	No	Optional sender display name (e.g., 'Peter Hartree'). If provided, the From header will be formatted as 'Name <email>'.
`thread_id`	No	Optional Gmail thread ID to reply within. When in_reply_to is omitted, replies to the latest non-draft, non-trash message with an RFC Message-ID.
`from_email`	No	Optional 'Send As' alias email address. Must be configured in Gmail settings (Settings > Accounts > Send mail as). If not provided, uses the account's default Send As address, falling back to the authenticated user's email when Gmail returns no usable Send-As entry or settings access is not authorized.
`references`	No	Optional Message-ID ancestry chain. Normally omit when thread_id is provided; the server derives the chain through the selected reply target.
`attachments`	No	Optional list of attachments. Each can have: 'url' (fetch from URL — works with MCP attachment URLs from get_drive_file_download_url / get_gmail_attachment_content), OR 'path' (file path, auto-encodes), OR 'content' (standard base64, not urlsafe) + 'filename'. Optional 'mime_type'. Optional 'content_id' (string) makes the attachment inline-rendered: it lands in a multipart/related part with `Content-ID: <content_id>` and `Content-Disposition: inline`, and the HTML body can reference it via `<img src="cid:<content_id>">` (RFC 2392). Without `content_id` the attachment is a regular multipart/mixed attachment.
`body_format`	No	Email body format. Use 'plain' for plaintext or 'html' for HTML content.	plain
`in_reply_to`	No	Optional RFC Message-ID to explicitly reply to a specific message (e.g., '<message123@gmail.com>'). Omit to reply to the latest eligible message in thread_id.
`quote_original`	No	Whether to include the original message as a quoted reply. Only has an effect when thread_id is provided. Defaults to false.
`include_signature`	No	Whether to append the Gmail signature from Settings > Signature when available. Defaults to true.
`user_google_email`	Yes	The user's Google email address. Required for authentication.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed19 schema fields changedv1.28.0Sep 24, 2026

removedInput schema / properties / attachments / anyOf

Removed value: -[
-  {
-    "items": {
-      "additionalProperties": true,
-      "type": "object"
-    },
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]

addedInput schema / properties / attachments / items

Added value: +{
+  "additionalProperties": true,
+  "type": "object"
+}

addedInput schema / properties / attachments / type
```
Added value: +"array"
```

removedInput schema / properties / bcc / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedInput schema / properties / bcc / type
```
Added value: +"string"
```

removedInput schema / properties / cc / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedInput schema / properties / cc / type
```
Added value: +"string"
```

removedInput schema / properties / from_email / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedInput schema / properties / from_email / type
```
Added value: +"string"
```

removedInput schema / properties / from_name / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedInput schema / properties / from_name / type
```
Added value: +"string"
```

removedInput schema / properties / in_reply_to / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedInput schema / properties / in_reply_to / type
```
Added value: +"string"
```

removedInput schema / properties / references / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedInput schema / properties / references / type
```
Added value: +"string"
```

removedInput schema / properties / thread_id / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedInput schema / properties / thread_id / type
```
Added value: +"string"
```

removedInput schema / properties / to / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedInput schema / properties / to / type
```
Added value: +"string"
```

Changed4 schema fields changedv1.25.2Aug 30, 2026

changedInput schema / properties / from_email / description

Previous value: -"Optional 'Send As' alias email address. Must be configured in Gmail settings (Settings > Accounts > Send mail as). If not provided, uses the authenticated user's email."New value: +"Optional 'Send As' alias email address. Must be configured in Gmail settings (Settings > Accounts > Send mail as). If not provided, uses the account's default Send As address, falling back to the authenticated user's email when Gmail returns no usable Send-As entry or settings access is not authorized."

changedInput schema / properties / in_reply_to / description

Previous value: -"Optional RFC Message-ID of the message being replied to (e.g., '<message123@gmail.com>')."New value: +"Optional RFC Message-ID to explicitly reply to a specific message (e.g., '<message123@gmail.com>'). Omit to reply to the latest eligible message in thread_id."

changedInput schema / properties / references / description

Previous value: -"Optional chain of Message-IDs for proper threading."New value: +"Optional Message-ID ancestry chain. Normally omit when thread_id is provided; the server derives the chain through the selected reply target."

changedInput schema / properties / thread_id / description

Previous value: -"Optional Gmail thread ID to reply within."New value: +"Optional Gmail thread ID to reply within. When in_reply_to is omitted, replies to the latest non-draft, non-trash message with an RFC Message-ID."

Changed1 schema field changedv1.24.0Aug 13, 2026

changedInput schema / properties / quote_original / description

Previous value: -"Whether to include the original message as a quoted reply. Requires thread_id. Defaults to false."New value: +"Whether to include the original message as a quoted reply. Only has an effect when thread_id is provided. Defaults to false."

Changed21 schema fields changedv1.0.1Jul 31, 2026

addedInput schema / additionalProperties
```
Added value: +false
```

addedInput schema / properties / attachments

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "additionalProperties": true,
+        "type": "object"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Optional list of attachments. Each can have: 'url' (fetch from URL — works with MCP attachment URLs from get_drive_file_download_url / get_gmail_attachment_content), OR 'path' (file path, auto-encodes), OR 'content' (standard base64, not urlsafe) + 'filename'. Optional 'mime_type'. Optional 'content_id' (string) makes the attachment inline-rendered: it lands in a multipart/related part with `Content-ID: <content_id>` and `Content-Disposition: inline`, and the HTML body can reference it via `<img src=\"cid:<content_id>\">` (RFC 2392). Without `content_id` the attachment is a regular multipart/mixed attachment."
+}

addedInput schema / properties / bcc

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Optional BCC email address."
+}

removedInput schema / properties / body / title
```
Removed value: -"Body"
```

addedInput schema / properties / body_format

Added value: +{
+  "default": "plain",
+  "description": "Email body format. Use 'plain' for plaintext or 'html' for HTML content.",
+  "enum": [
+    "plain",
+    "html"
+  ],
+  "type": "string"
+}

addedInput schema / properties / cc

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Optional CC email address."
+}

addedInput schema / properties / from_email

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Optional 'Send As' alias email address. Must be configured in Gmail settings (Settings > Accounts > Send mail as). If not provided, uses the authenticated user's email."
+}

addedInput schema / properties / from_name

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Optional sender display name (e.g., 'Peter Hartree'). If provided, the From header will be formatted as 'Name <email>'."
+}

addedInput schema / properties / in_reply_to

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Optional RFC Message-ID of the message being replied to (e.g., '<message123@gmail.com>')."
+}

addedInput schema / properties / include_signature

Added value: +{
+  "default": true,
+  "description": "Whether to append the Gmail signature from Settings > Signature when available. Defaults to true.",
+  "type": "boolean"
+}

addedInput schema / properties / quote_original

Added value: +{
+  "default": false,
+  "description": "Whether to include the original message as a quoted reply. Requires thread_id. Defaults to false.",
+  "type": "boolean"
+}

addedInput schema / properties / references

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Optional chain of Message-IDs for proper threading."
+}

removedInput schema / properties / service

Removed value: -{
-  "title": "service",
-  "type": "string"
-}

removedInput schema / properties / subject / title
```
Removed value: -"Subject"
```

addedInput schema / properties / thread_id

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Optional Gmail thread ID to reply within."
+}

removedInput schema / properties / to / title
```
Removed value: -"To"
```

addedInput schema / properties / user_google_email / description

Added value: +"The user's Google email address. Required for authentication."

removedInput schema / properties / user_google_email / title
```
Removed value: -"User Google Email"
```

changedInput schema / required

Previous value: -[
-  "service",
-  "user_google_email",
-  "subject",
-  "body"
-]New value: +[
+  "user_google_email",
+  "subject",
+  "body"
+]

removedInput schema / title

Removed value: -"draft_gmail_messageArguments"

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "result": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "result"
+  ],
+  "type": "object",
+  "x-fastmcp-wrap-result": true
+}

First observedv1.0.0Jun 10, 2025

TDQS

A4.4/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations, the description discloses critical runtime behavior: scheduling is impossible through the REST API, the Scheduled folder cannot be populated, and future delivery requires retaining the data and later calling send_gmail_message or users.drafts.send. It also references the draft ID returned by the tool, which is valuable for follow-up calls.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded and the scheduling caveat is clearly separated, making the long block scannable. The scheduled-send paragraph is slightly repetitive and could be tightened, but every sentence contributes safety-relevant guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 15 parameters, an output schema, and annotations, the description is complete: it covers behavior, the API scheduling limitation, Send As support, and the follow-up path for deferred delivery. Detailed parameter semantics and return expectations are already in the schema and output schema, so the description does not need to repeat them.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

All 15 parameters already have descriptions in the schema (100% coverage), so the baseline applies. The description's 'Send As' mention largely restates the from_email schema text rather than adding per-parameter detail. There is no extra semantic meaning beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource ('Creates a draft email in the user's Gmail account') and immediately narrows scope to new drafts, reply drafts, attachments, and Send As aliases. The 'draft' wording clearly separates it from send_gmail_message before the scheduling note names that sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It names the relevant sending sibling (send_gmail_message) as part of the scheduling workaround and explicitly states that Gmail's API cannot place a message in the Scheduled folder. However, it lacks a direct 'use this for drafts, use send_gmail_message for immediate sends' boundary, leaving that distinction mostly implied by the word 'draft'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server