Which integrations are available for this server?

Provides comprehensive tools for managing email accounts, including searching, reading, sending, and deleting emails, as well as managing labels, filters, and attachments.

How do I use Gmail MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Gmail MCP Server search for recent emails from GitHub and summarize the main points" 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 MCP Server

A comprehensive Model Context Protocol (MCP) server for Gmail, providing 24 tools for full email management including sending, receiving, labels, filters, attachments, and batch operations.

Features

24 Gmail Tools: Full email operations, label management, filters, batch operations, and attachments
Multi-Account Support: Manage multiple Gmail accounts with --account flag
OAuth Authentication: Secure authentication with automatic token refresh
Attachment Support: Download and send attachments
Batch Operations: Efficiently modify or delete up to 1000 emails at once
Filter Templates: Pre-built filter templates for common use cases
MCP Resources: Access messages, threads, and labels via URI

Prerequisites

Node.js 18+
A Google Cloud Project with Gmail API enabled
OAuth 2.0 credentials (Desktop app type)

Setup

1. Create Google Cloud OAuth Credentials

Go to Google Cloud Console
Create a new project or select an existing one
Enable the Gmail API:
- Navigate to "APIs & Services" > "Library"
- Search for "Gmail API"
- Click "Enable"
Create OAuth credentials:
- Go to "APIs & Services" > "Credentials"
- Click "Create Credentials" > "OAuth Client ID"
- If prompted, configure the OAuth consent screen:
  - Choose "External" user type (or "Internal" for Workspace)
  - Fill in required fields (app name, user support email, developer email)
  - Add scopes: gmail.modify and gmail.settings.basic
  - Add your email as a test user
- Select "Desktop app" as the application type
- Name it (e.g., "Gmail MCP")
- Click "Create"
Download the JSON credentials file

2. Install and Configure

# Clone or download the project cd gmail-mcp # Install dependencies npm install # Build the project npm run build # Create config directory and save credentials mkdir -p ~/.gmail-mcp cp /path/to/downloaded/credentials.json ~/.gmail-mcp/credentials.json # Authenticate (for a single account) node dist/index.js auth # Or authenticate with a named account (for multi-account support) node dist/index.js auth --account work node dist/index.js auth --account personal

The auth command will:

Open your browser to Google's OAuth consent page
Ask you to authorize the application
Save the tokens to ~/.gmail-mcp/tokens/<account>.json

To list authenticated accounts:

node dist/index.js list

3. Add to Claude Code

For a single account:

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

For multiple accounts, add each with its own name:

claude mcp add gmail-work -- node /path/to/gmail-mcp/dist/index.js --account work claude mcp add gmail-personal -- node /path/to/gmail-mcp/dist/index.js --account personal

Or add manually to your Claude Code MCP settings:

{ "mcpServers": { "gmail-work": { "command": "node", "args": ["/path/to/gmail-mcp/dist/index.js", "--account", "work"] }, "gmail-personal": { "command": "node", "args": ["/path/to/gmail-mcp/dist/index.js", "--account", "personal"] } } }

Available Tools

Email Operations (7 tools)

Tool	Description
`search_emails`	Search with Gmail query syntax, pagination
`read_email`	Full message with headers, body, attachment info
`send_email`	Send with to/cc/bcc, attachments, threading
`draft_email`	Create draft without sending
`delete_email`	Trash or permanent delete
`modify_email`	Add/remove labels from message
`get_thread`	Get full conversation thread

Label Management (6 tools)

Tool	Description
`list_labels`	All labels (system + user)
`create_label`	Create with color, visibility
`update_label`	Rename, change settings
`delete_label`	Remove custom label
`get_or_create_label`	Idempotent label creation
`get_label`	Get single label details

Filter Management (5 tools)

Tool	Description
`list_filters`	All Gmail filters
`get_filter`	Single filter details
`create_filter`	Custom criteria + actions
`delete_filter`	Remove filter
`create_filter_from_template`	Preset templates

Batch Operations (2 tools)

Tool	Description
`batch_modify_emails`	Bulk add/remove labels (50 at a time)
`batch_delete_emails`	Bulk delete with fallback

Attachments (2 tools)

Tool	Description
`download_attachment`	Save to local filesystem
`list_attachments`	Get attachment metadata for message

Utilities (2 tools)

Tool	Description
`get_profile`	User email address, history ID
`get_quota`	Storage usage info

Resources

Resource	URI Pattern
Message	`gmail://messages/{messageId}`
Thread	`gmail://threads/{threadId}`
Label	`gmail://labels/{labelId}`

Usage Examples

Search for unread emails

Search my Gmail for unread emails from the last week

Read a specific email

Read the email with ID 18abc123def

Send an email

Send an email to john@example.com with subject "Hello" and body "Hi John, how are you?"

Create a filter

Create a Gmail filter that labels all emails from newsletter@example.com with "Newsletters"

Batch operations

Move all emails matching "is:unread older_than:30d" to trash

OAuth Scopes

The server uses these scopes:

gmail.modify - Read, compose, send, and modify emails and labels
gmail.settings.basic - Manage mail filters

File Structure

gmail-mcp/ ├── src/ │ ├── index.ts # CLI entry point │ ├── server.ts # MCP server setup │ ├── gmail/ │ │ ├── auth.ts # OAuth flow │ │ ├── client.ts # Gmail API wrapper │ │ ├── mime.ts # MIME parsing/encoding │ │ └── types.ts # Type definitions │ ├── tools/ │ │ ├── index.ts # Tool registration │ │ ├── emails.ts # Email operations │ │ ├── labels.ts # Label management │ │ ├── filters.ts # Filter management │ │ ├── batch.ts # Batch operations │ │ └── attachments.ts # Attachment handling │ ├── resources/ │ │ └── index.ts # MCP resources │ └── schemas/ │ └── index.ts # Zod schemas ├── package.json ├── tsconfig.json └── README.md

Security

Credentials stored in ~/.gmail-mcp/ with restricted permissions (0600)
Per-account tokens stored in ~/.gmail-mcp/tokens/
Tokens automatically refresh when expired
OAuth callback only on localhost
No external telemetry or data collection

Troubleshooting

"Not authenticated" error

Run node dist/index.js auth --account <name> to authenticate.

"Permission denied" error

Ensure your OAuth credentials have the correct scopes and the Gmail API is enabled.

Token refresh fails

Delete ~/.gmail-mcp/tokens/<account>.json and run auth again.

Port 3000 in use

The OAuth callback requires port 3000. Close any applications using this port.

License

MIT

Gmail MCP Server

Gmail MCP Server

Features

Prerequisites

Setup

1. Create Google Cloud OAuth Credentials

2. Install and Configure

3. Add to Claude Code

Available Tools

Email Operations (7 tools)

Label Management (6 tools)

Filter Management (5 tools)

Batch Operations (2 tools)

Attachments (2 tools)

Utilities (2 tools)

Resources

Usage Examples

Search for unread emails

Read a specific email

Send an email

Create a filter

Batch operations

OAuth Scopes

File Structure

Security

Troubleshooting

"Not authenticated" error

"Permission denied" error

Token refresh fails

Port 3000 in use

License

Resources

New MCP Servers

Latest Blog Posts

MCP directory API