Skip to main content
Glama
gmail-labels-mcp-server

gmail-labels-mcp-server

by YimingYAN

Gmail Labels MCP Server

An MCP server for Gmail label management. Fills the gap in the official Gmail MCP connector, which lacks label/tag operations.

Handles OAuth2 automatically — authenticate once, and the server refreshes tokens forever.

Tools

Tool

Description

gmail_list_labels

List all labels with IDs, names, and message counts

gmail_create_label

Create a new label (supports nesting with /)

gmail_delete_label

Delete a user-created label

gmail_get_message_labels

Get current labels on a specific message

gmail_modify_message_labels

Add/remove labels on a specific message

gmail_modify_thread_labels

Add/remove labels on an entire thread

gmail_bulk_label_by_search

Search messages and bulk apply label changes

Related MCP server: Gmail MCP Server

Setup

1. Create a Google Cloud project and enable the Gmail API

  1. Go to the Google Cloud Console

  2. Create a new project (or select an existing one)

  3. Navigate to APIs & Services > Library

  4. Search for Gmail API and click Enable

2. Create OAuth2 credentials

  1. Go to APIs & Services > Credentials

  2. Click Create Credentials > OAuth Client ID

  3. If prompted, configure the OAuth consent screen first:

    • Choose External user type (or Internal if using Google Workspace)

    • Fill in the app name (e.g. "Gmail Labels MCP") and your email

    • Add the scope https://mail.google.com/

    • Add your email as a test user

    • Save and go back to creating credentials

  4. Select Desktop app as the application type

  5. Give it a name (e.g. "Gmail Labels MCP")

  6. Click Create and copy the Client ID and Client Secret

3. Install and authenticate

Option A: Install from npm (recommended)

npm install -g gmail-labels-mcp-server
GOOGLE_CLIENT_ID=your_client_id GOOGLE_CLIENT_SECRET=your_client_secret gmail-labels-mcp-server --auth

Option B: Clone and build from source

git clone https://github.com/YimingYAN/gmail-labels-mcp-server.git
cd gmail-labels-mcp-server
npm install && npm run build
GOOGLE_CLIENT_ID=your_client_id GOOGLE_CLIENT_SECRET=your_client_secret npm run auth

This opens a browser for Google consent. Approve Gmail access, and credentials are saved to ~/.gmail-labels-mcp/credentials.json. You only need to do this once.

4. Configure your client

Claude Code

claude mcp add gmail-labels -- npx gmail-labels-mcp-server

Or if installed from source:

claude mcp add gmail-labels -- node /path/to/gmail-labels-mcp-server/dist/index.js

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "gmail-labels": {
      "command": "npx",
      "args": ["gmail-labels-mcp-server"]
    }
  }
}

No env vars needed — the server reads credentials from ~/.gmail-labels-mcp/credentials.json and auto-refreshes tokens.

Example Usage

  • "List all my Gmail labels"

  • "Create a label called 'Crypto/Compliance'"

  • "Tag message [id] with the Finance label"

  • "Mark message [id] as read" (removes UNREAD label)

  • "Archive all emails from newsletter@example.com"

  • "Star message [id]" (adds STARRED label)

  • "What labels does message [id] currently have?"

Notes

  • System label IDs: INBOX, SENT, TRASH, SPAM, STARRED, IMPORTANT, UNREAD

  • User label IDs follow the format Label_XXXXXXXXXX

  • Use gmail_list_labels first to discover label IDs before modifying messages

  • "Mark as read" = remove UNREAD label; "Mark as unread" = add UNREAD label

  • To re-authenticate: delete ~/.gmail-labels-mcp/credentials.json and re-run the auth step

License

MIT

Available Tools

7 tools
gmail_create_labelCreate Gmail LabelA

Create a new user label (tag) in Gmail.

Args:

  • name (string): Label name. Supports nesting with "/" (e.g., "Finance/Invoices")

Returns: The created label with its ID, name, and visibility settings.

Examples:

  • Use when: "Create a label called 'Compliance'"

  • Use when: "Add a new Gmail tag 'Projects/Alpha'"

Inputs: name (required).

gmail_delete_labelDelete Gmail LabelA
DestructiveIdempotent

Delete a user-created label from Gmail. System labels cannot be deleted.

Args:

  • label_id (string): The label ID to delete (use gmail_list_labels to find IDs)

Note: Deleting a label removes it from all messages but does not delete the messages.

Examples:

  • Use when: "Delete the label with ID Label_123"

  • Use when: "Remove the 'OldProject' label"

Inputs: label_id (required).

gmail_get_message_labelsGet Current Labels on a Gmail MessageA
Read-onlyIdempotent

Retrieve the current labels on a specific Gmail message.

Args:

  • message_id (string): The Gmail message ID

Returns: Message metadata including subject, snippet, and current label IDs.

Examples:

  • Use when: "What labels does message abc123 have?"

  • Use when: "Is message abc123 starred?"

Inputs: message_id (required).

gmail_list_labelsList Gmail LabelsA
Read-onlyIdempotent

List all labels (tags) in the Gmail account.

Returns both system labels (INBOX, SENT, TRASH, etc.) and user-created labels. Use this to find label IDs needed for add/remove operations.

Returns: List of labels with their IDs, names, types, and message counts.

Examples:

  • Use when: "Show me all my Gmail labels"

  • Use when: "What label ID does 'Finance' have?"

Inputs: no named parameters.

gmail_modify_message_labelsModify Labels on a Gmail MessageA

Add or remove labels (tags) on a specific Gmail message.

Args:

  • message_id (string): The Gmail message ID

  • add_label_ids (string[]): List of label IDs to add (optional)

  • remove_label_ids (string[]): List of label IDs to remove (optional)

Use gmail_list_labels to find label IDs. Common system label IDs:

  • INBOX, STARRED, IMPORTANT, SENT, TRASH, SPAM, UNREAD, READ

Returns: Updated message with its current label IDs.

Examples:

  • Use when: "Tag message abc123 with label Label_456"

  • Use when: "Remove INBOX label from message abc123 (archive it)"

  • Use when: "Star message abc123" -> add_label_ids: ["STARRED"]

Inputs: message_id (required), add_label_ids, remove_label_ids.

gmail_modify_thread_labelsModify Labels on a Gmail ThreadA

Add or remove labels on all messages in a Gmail thread at once.

Args:

  • thread_id (string): The Gmail thread ID

  • add_label_ids (string[]): Label IDs to add to all messages in the thread

  • remove_label_ids (string[]): Label IDs to remove from all messages in the thread

Returns: Updated thread with message count and affected message IDs.

Examples:

  • Use when: "Label this entire conversation as 'Compliance'"

  • Use when: "Archive this thread" -> remove_label_ids: ["INBOX"]

Inputs: thread_id (required), add_label_ids, remove_label_ids.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action: label CRUD, message label operations, thread label operations, and bulk search modifications. There is no overlap between tools; even the three modifying tools differ by scope (single message, single thread, bulk search).

    Naming Consistency5/5

    All tool names follow a consistent gmail_ prefix with a verb_noun pattern (e.g., list_labels, create_label, modify_message_labels). Even 'bulk_label_by_search' uses a clear action-object-modifier structure. The naming is uniform and predictable.

    Tool Count5/5

    Seven tools is well-scoped for a Gmail label management server. It covers label administration and all common ways to apply/remove labels without excess overlap or missing essentials. The set feels neither sparse nor bloated.

    Completeness4/5

    The tool set provides label CRUD (list, create, delete) and comprehensive label modification via message, thread, and bulk search. The only notable gap is the lack of an update/rename label operation, which is a minor omission that agents can work around by creating a new label and migrating.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      D
      maintenance
      Enables comprehensive Gmail management through the Gmail API, including sending/receiving emails, organizing labels and threads, managing drafts, and configuring account settings with secure OAuth2 authentication.
      64
      696 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to manage Gmail through natural language, supporting operations like sending, searching, and reading emails. It includes comprehensive label management, batch processing, and a streamlined OAuth2 auto-authentication flow.
      MIT