Skip to main content
Glama
faithk7

Gmail MCP Server

by faithk7
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Hybrid

create_draft

Create a draft email in Gmail with recipients, subject, and body, or use raw base64url encoded format for complete message control.

Instructions

Create a draft email in Gmail. Note the mechanics of the raw parameter.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
rawNoThe entire email message in base64url encoded RFC 2822 format, ignores params.to, cc, bcc, subject, body, includeBodyHtml if provided
threadIdNoThe thread ID to associate this draft with
toNoList of recipient email addresses
ccNoList of CC recipient email addresses
bccNoList of BCC recipient email addresses
subjectNoThe subject of the email
bodyNoThe body of the email
includeBodyHtmlNoWhether to include the parsed HTML in the return for each body, excluded by default because they can be excessively large

Implementation Reference

  • src/index.ts:274-295 (handler)
    Handler function for the 'create_draft' tool. Handles input parameters, constructs raw message if not provided, calls Gmail API to create the draft, processes the payload, and formats the response.
    async (params) => {
  return handleTool(config, async (gmail: gmail_v1.Gmail) => {
    let raw = params.raw
    if (!raw) raw = await constructRawMessage(gmail, params)

    const draftCreateParams: DraftCreateParams = { userId: 'me', requestBody: { message: { raw } } }
    if (params.threadId && draftCreateParams.requestBody?.message) {
      draftCreateParams.requestBody.message.threadId = params.threadId
    }

    const { data } = await gmail.users.drafts.create(draftCreateParams)

    if (data.message?.payload) {
      data.message.payload = processMessagePart(
        data.message.payload,
        params.includeBodyHtml
      )
    }

    return formatResponse(data)
  })
}
  • src/index.ts:265-273 (schema)
    Input schema (Zod) for the 'create_draft' tool defining parameters like raw, threadId, to, cc, bcc, subject, body, and includeBodyHtml.
      raw: z.string().optional().describe("The entire email message in base64url encoded RFC 2822 format, ignores params.to, cc, bcc, subject, body, includeBodyHtml if provided"),
  threadId: z.string().optional().describe("The thread ID to associate this draft with"),
  to: z.array(z.string()).optional().describe("List of recipient email addresses"),
  cc: z.array(z.string()).optional().describe("List of CC recipient email addresses"),
  bcc: z.array(z.string()).optional().describe("List of BCC recipient email addresses"),
  subject: z.string().optional().describe("The subject of the email"),
  body: z.string().optional().describe("The body of the email"),
  includeBodyHtml: z.boolean().optional().describe("Whether to include the parsed HTML in the return for each body, excluded by default because they can be excessively large")
},
  • src/index.ts:262-296 (registration)
    Registration of the 'create_draft' tool on the MCP server, including name, description, schema, and handler.
    server.tool("create_draft",
  "Create a draft email in Gmail. Note the mechanics of the raw parameter.",
  {
    raw: z.string().optional().describe("The entire email message in base64url encoded RFC 2822 format, ignores params.to, cc, bcc, subject, body, includeBodyHtml if provided"),
    threadId: z.string().optional().describe("The thread ID to associate this draft with"),
    to: z.array(z.string()).optional().describe("List of recipient email addresses"),
    cc: z.array(z.string()).optional().describe("List of CC recipient email addresses"),
    bcc: z.array(z.string()).optional().describe("List of BCC recipient email addresses"),
    subject: z.string().optional().describe("The subject of the email"),
    body: z.string().optional().describe("The body of the email"),
    includeBodyHtml: z.boolean().optional().describe("Whether to include the parsed HTML in the return for each body, excluded by default because they can be excessively large")
  },
  async (params) => {
    return handleTool(config, async (gmail: gmail_v1.Gmail) => {
      let raw = params.raw
      if (!raw) raw = await constructRawMessage(gmail, params)

      const draftCreateParams: DraftCreateParams = { userId: 'me', requestBody: { message: { raw } } }
      if (params.threadId && draftCreateParams.requestBody?.message) {
        draftCreateParams.requestBody.message.threadId = params.threadId
      }

      const { data } = await gmail.users.drafts.create(draftCreateParams)

      if (data.message?.payload) {
        data.message.payload = processMessagePart(
          data.message.payload,
          params.includeBodyHtml
        )
      }

      return formatResponse(data)
    })
  }
)
  • src/index.ts:50-80 (helper)
    Shared helper function 'handleTool' used by create_draft (and other tools) to manage OAuth2 authentication, credential validation, Gmail client creation, API execution, and error handling.
    const handleTool = async (queryConfig: Record<string, any> | undefined, apiCall: (gmail: gmail_v1.Gmail) => Promise<any>) => {
  try {
    const oauth2Client = queryConfig ? createOAuth2Client(queryConfig) : defaultOAuth2Client
    if (!oauth2Client) throw new Error('OAuth2 client could not be created, please check your credentials')

    const credentialsAreValid = await validateCredentials(oauth2Client)
    if (!credentialsAreValid) throw new Error('OAuth2 credentials are invalid, please re-authenticate')

    const gmailClient = queryConfig ? google.gmail({ version: 'v1', auth: oauth2Client }) : defaultGmailClient
    if (!gmailClient) throw new Error('Gmail client could not be created, please check your credentials')

    const result = await apiCall(gmailClient)
    return result
  } catch (error: any) {
    // Check for specific authentication errors
    if (
      error.message?.includes("invalid_grant") ||
      error.message?.includes("refresh_token") ||
      error.message?.includes("invalid_client") ||
      error.message?.includes("unauthorized_client") ||
      error.code === 401 ||
      error.code === 403
    ) {
      return formatResponse({
        error: `Authentication failed: ${error.message}. Please re-authenticate by running: npx @shinzolabs/gmail-mcp auth`,
      });
    }

    return formatResponse({ error: `Tool execution failed: ${error.message}` });
  }
}
  • src/index.ts:200-235 (helper)
    Helper function 'constructRawMessage' used by create_draft to build the base64url-encoded RFC 2822 raw message from parameters, handling thread quoting and headers.
    const constructRawMessage = async (gmail: gmail_v1.Gmail, params: NewMessage) => {
  let thread: Thread | null = null
  if (params.threadId) {
    const threadParams = { userId: 'me', id: params.threadId, format: 'full' }
    const { data } = await gmail.users.threads.get(threadParams)
    thread = data
  }

  const message = []
  if (params.to?.length) message.push(`To: ${wrapTextBody(params.to.join(', '))}`)
  if (params.cc?.length) message.push(`Cc: ${wrapTextBody(params.cc.join(', '))}`)
  if (params.bcc?.length) message.push(`Bcc: ${wrapTextBody(params.bcc.join(', '))}`)
  if (thread) {
    message.push(...getThreadHeaders(thread).map(header => wrapTextBody(header)))
  } else if (params.subject) {
    message.push(`Subject: ${wrapTextBody(params.subject)}`)
  } else {
    message.push('Subject: (No Subject)')
  }
  message.push('Content-Type: text/plain; charset="UTF-8"')
  message.push('Content-Transfer-Encoding: quoted-printable')
  message.push('MIME-Version: 1.0')
  message.push('')

  if (params.body) message.push(wrapTextBody(params.body))

  if (thread) {
    const quotedContent = getQuotedContent(thread)
    if (quotedContent) {
      message.push('')
      message.push(wrapTextBody(quotedContent))
    }
  }

  return Buffer.from(message.join('\r\n')).toString('base64url').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
}

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

B3.1/5.0
Behavior2/5

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

No annotations provided, so the description carries full burden. It mentions 'mechanics of the raw parameter' but fails to disclose that the raw parameter overrides other fields, which is a critical behavioral trait.

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 description is concise with two short sentences, front-loading the main purpose. No unnecessary information, though it could be slightly more structured.

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

Completeness2/5

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

Given no output schema and the complexity of the raw parameter overriding, the description is incomplete. It does not explain the implications of the raw parameter or provide a complete picture of the tool's behavior.

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?

Schema coverage is 100% with detailed descriptions for each parameter. The description adds minimal value by drawing attention to the raw parameter, but does not significantly enhance understanding beyond the schema.

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 clearly states the action ('Create a draft email') and the resource ('in Gmail'), which is specific and distinguishable from sibling tools like 'send_draft' or 'delete_draft'.

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

Usage Guidelines2/5

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 (e.g., send_draft). The description only hints at the raw parameter mechanics but does not provide usage context.

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

Deploy Server

Other Tools