Gmail

v1.0.0552 callsOAuthGitHub

Documentation

Guide

Send, search, and manage Gmail — directly from your AI workflows.

A Model Context Protocol (MCP) server that exposes Gmail's API for reading, sending, organizing, and managing email messages, threads, labels, and drafts.

Overview

The Gmail MCP Server provides full programmatic access to Gmail through a stateless, multi-tenant interface:

Send, reply to, and draft emails with optional attachments
Search and retrieve messages and threads using Gmail's native query syntax
Organize your inbox with label management and read/unread state control

Perfect for:

Automating email workflows and notifications from AI agents
Building assistants that can read, respond to, and triage email
Integrating Gmail actions into LLM-powered pipelines

Tools

Returns the authenticated user's Gmail profile including email address and mailbox statistics.

Inputs:

none

output:

{
  "emailAddress": "user@gmail.com",
  "messagesTotal": 1024,
  "threadsTotal": 512,
  "historyId": "123456"
}

Fetches a single Gmail message by its ID in the requested format.

Inputs:

- `message_id` (string, required) — Gmail message ID
- `format` (string, optional) — Message format. Common values: `minimal`, `full`, `raw`, `metadata`. Default: `full`

output:

{
  "id": "18b1c2d3e4f5",
  "threadId": "18b1c2d3e4f5",
  "labelIds": ["INBOX", "UNREAD"],
  "payload"

Composes and sends a plain-text email to one or more recipients.

Inputs:

- `to` (string, required) — Recipient email address
- `subject` (string, required) — Email subject
- `body` (string, required) — Plain-text email body
- `cc` (string, optional) — Comma-separated CC recipients
- `bcc` (string, optional) — Comma-separated BCC recipients

output:

{
  "message": "Email sent successfully",
  "id": "18b1c2d3e4f5",
  "threadId"

Composes and sends an email with a file attachment from the local filesystem.

Inputs:

- `to` (string, required) — Recipient email address
- `subject` (string, required) — Email subject
- `body` (string, required) — Plain-text email body
- `attachment_path` (string, required) — Local filesystem path to the file attachment
- `cc` (string, optional) — Comma-separated CC recipients

output:

{
  "message": "Email with attachment sent successfully",
  "id": "18b1c2d3e4f5"

Sends a reply to an existing message, preserving the thread and original headers.

Inputs:

- `message_id` (string, required) — Gmail message ID of the message to reply to
- `body` (string, required) — Reply body text

output:

{
  "message": "Reply sent successfully",
  "id": "18b1c2d3e4f5",
  "threadId": "18b1c2d3e4f5"
}

Permanently deletes a message. This action cannot be undone.

Inputs:

- `message_id` (string, required) — Gmail message ID

output:

{
  "message": "Message 18b1c2d3e4f5 deleted successfully",
  "id": "18b1c2d3e4f5"
}

Moves a message to the trash folder. The message can be recovered until the trash is emptied.

Inputs:

- `message_id` (string, required) — Gmail message ID

output:

{
  "message": "Message moved to trash successfully",
  "id": "18b1c2d3e4f5"
}

Restores a message from the trash back to the inbox.

Inputs:

- `message_id` (string, required) — Gmail message ID

output:

{
  "message": "Message removed from trash successfully",
  "id": "18b1c2d3e4f5"
}

Applies or removes one or more labels from a message in a single operation.

Inputs:

- `message_id` (string, required) — Gmail message ID
- `add_labels` (list of strings, optional) — Label IDs to add to the message
- `remove_labels` (list of strings, optional) — Label IDs to remove from the message

output:

{
  "message": "Labels modified successfully",
  "id": "18b1c2d3e4f5",
  "labelIds": ["INBOX",

Returns all system and user-defined labels available in the authenticated user's mailbox.

Inputs:

none

output:

{
  "count": 12,
  "labels": [
    { "id": "INBOX", "name": "INBOX", "type": "system" },
    { "id":

Creates a new user-defined label with configurable visibility settings.

Inputs:

- `name` (string, required) — Label name
- `label_list_visibility` (string, optional) — Visibility in the label list. Values: `labelShow`, `labelShowIfUnread`, `labelHide`. Default: `labelShow`
- `message_list_visibility` (string, optional) — Visibility in message lists. Values: `show`, `hide`. Default: `show`

output:

{
  "message": "Label created successfully",
  "label": {
    "id": "Label_456",

Permanently deletes a user-defined label. Messages with this label are not deleted.

Inputs:

- `label_id` (string, required) — Label ID to delete

output:

{
  "message": "Label Label_456 deleted successfully",
  "id": "Label_456"
}

Searches messages using Gmail's native query syntax and returns matching message stubs.

Inputs:

- `query` (string, required) — Gmail search query e.g. `from:example@gmail.com`, `is:unread`, `subject:invoice`
- `max_results` (integer, optional) — Maximum number of results to return, capped at 500. Default: `10`

output:

{
  "count": 3,
  "messages": [
    { "id": "18b1c2d3e4f5"

Removes the UNREAD label from a message, marking it as read.

Inputs:

- `message_id` (string, required) — Gmail message ID

output:

{
  "message": "Message marked as read successfully",
  "id": "18b1c2d3e4f5"
}

Adds the UNREAD label to a message, marking it as unread.

Inputs:

- `message_id` (string, required) — Gmail message ID

output:

{
  "message": "Message marked as unread successfully",
  "id": "18b1c2d3e4f5"
}

Fetches a full email thread including all messages it contains.

Inputs:

- `thread_id` (string, required) — Gmail Thread ID
- `format` (string, optional) — Message format within the thread. Common values: `minimal`, `full`, `raw`, `metadata`. Default: `full`

output:

{
  "id": "18b1c2d3e4f5",
  "historyId": "123456",
  "messages": [ { "...": "message objects" } ]
}

Returns a list of draft messages in the authenticated user's mailbox.

Inputs:

- `max_results` (integer, optional) — Maximum number of drafts to return, capped at 500. Default: `10`

output:

{
  "count": 2,
  "drafts": [
    { "id": "r123456", "message": { "id": "18b1c2d3e4f5"

Creates a new draft email without sending it.

Inputs:

- `to` (string, required) — Recipient email address
- `subject` (string, required) — Draft subject
- `body` (string, required) — Draft body text

output:

{
  "message": "Draft created successfully",
  "id": "r123456"
}

API Parameters Reference

Message format values:

full      — Full message payload with body decoded (default)
minimal   — Only message IDs and labels, no payload
raw       — Full message as RFC 2822 base64url-encoded string
metadata  — Headers only, no body

gmail Search Query Syntax:

from:user@example.com    — Messages from a sender
to:user@example.com      — Messages to a recipient
subject:invoice          — Messages with word in subject
is:unread                — Unread messages
is:starred               — Starred messages

Troubleshooting

Resources

Gmail API Documentation — Official API reference
Gmail API Reference — Complete endpoint reference
FastMCP Docs — FastMCP specification
FastMCP Credentials — FastMCP Credentials package for credential handling

Help Improve This Server

Missing a tool?

Found a bug?

Have an idea for an improvement?

Share your feedback directly with the maintainers - every feedback helps make this server better for everyone.

Open GitHub Issues →