gmail-labels-mcp-server
Provides tools for managing Gmail labels, including listing, creating, deleting labels, and modifying labels on messages and threads.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@gmail-labels-mcp-server list all my Gmail labels"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| List all labels with IDs, names, and message counts |
| Create a new label (supports nesting with |
| Delete a user-created label |
| Get current labels on a specific message |
| Add/remove labels on a specific message |
| Add/remove labels on an entire thread |
| 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
Go to the Google Cloud Console
Create a new project (or select an existing one)
Navigate to APIs & Services > Library
Search for Gmail API and click Enable
2. Create OAuth2 credentials
Go to APIs & Services > Credentials
Click Create Credentials > OAuth Client ID
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
Select Desktop app as the application type
Give it a name (e.g. "Gmail Labels MCP")
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 --authOption 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 authThis 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-serverOr if installed from source:
claude mcp add gmail-labels -- node /path/to/gmail-labels-mcp-server/dist/index.jsClaude 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,UNREADUser label IDs follow the format
Label_XXXXXXXXXXUse
gmail_list_labelsfirst to discover label IDs before modifying messages"Mark as read" = remove
UNREADlabel; "Mark as unread" = addUNREADlabelTo re-authenticate: delete
~/.gmail-labels-mcp/credentials.jsonand re-run the auth step
License
MIT
Available Tools
7 toolsgmail_bulk_label_by_searchBulk Label Gmail Messages by Search QueryA
Search Gmail messages using a query and apply label changes to all matching messages.
Args:
query (string): Gmail search query (same syntax as Gmail search box)
add_label_ids (string[]): Label IDs to add to all matching messages
remove_label_ids (string[]): Label IDs to remove from all matching messages
max_results (number): Max messages to process (default: 20, max: 100)
Common query examples:
"from:sender@example.com" - emails from a sender
"subject:invoice" - emails with 'invoice' in subject
"is:unread" - unread emails
"after:2024/01/01 before:2024/12/31" - date range
Returns: Count of messages updated and their IDs.
Examples:
Use when: "Label all emails from compliance@firm.com as 'Compliance'"
Use when: "Archive all emails with subject 'Newsletter'"
Inputs: query (required), max_results, add_label_ids, remove_label_ids.
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 LabelADestructiveIdempotent
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 MessageARead-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 LabelsARead-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
Scored across 7 tools
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).
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.
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.
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
Related MCP Connectors
Manage Gmail end-to-end: search, read, send, draft, label, and organize threads. Automate workflow…
Manage Gmail messages, threads, labels, drafts, and settings from your workflows. Send and organiz…
Permissioned access to Gmail, Drive and Calendar via the user's own Google account
Gmail for agents: create inboxes, read and reply to mail, send email, manage domains. OAuth sign-in.
Related MCP Servers
- AlicenseCqualityDmaintenanceEnables 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.64696 npm1MIT
- AlicenseBqualityDmaintenanceEnables comprehensive Gmail management including sending, reading, and organizing emails, managing labels, drafts, threads, and configuring account settings through the Gmail API with secure OAuth2 authentication.64696 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables reading, sending, archiving, and managing Gmail emails and labels through Google OAuth authentication, acting as an OAuth proxy to the Gmail API.239 npm12MIT
- AlicenseNot gradedqualityDmaintenanceEnables 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