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

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