# Gmail [Health: Active]

**Category:** 💬 Communication  
**Repository:** https://github.com/domdomegg/gmail-mcp.git  
**GitHub Stars:** 12  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/gmail

## Description
Allow AI systems to read, send, archive, and manage emails via Gmail.

## Tools
Capabilities this server exposes over MCP:

- **gmail_get_profile** — Get user's email address and profile info
- **Messages**
- **gmail_messages_list** — Search/list messages (consider `gmail_threads_list` instead)
- **gmail_message_get** — Get a single message
- **gmail_message_send** — Send an email
- **gmail_message_forward** — Forward an email to new recipients
- **gmail_message_modify** — Add/remove labels
- **gmail_message_archive** — Archive (remove from inbox)
- **gmail_message_trash** — Move to trash
- **gmail_message_untrash** — Restore from trash
- **gmail_message_delete** — Permanently delete
- **gmail_messages_batch_modify** — Bulk label changes
- **gmail_messages_batch_delete** — Bulk permanent delete
- **Threads**
- **gmail_threads_list** — Search/list threads (recommended)
- **gmail_thread_get** — Get all messages in a thread (recommended)
- **gmail_thread_modify** — Add/remove labels
- **gmail_thread_trash** — Move to trash
- **gmail_thread_untrash** — Restore from trash
- **gmail_thread_delete** — Permanently delete
- **Drafts**
- **gmail_drafts_list** — List drafts
- **gmail_draft_get** — Get a draft
- **gmail_draft_create** — Create a draft
- **gmail_draft_update** — Update a draft
- **gmail_draft_send** — Send a draft
- **gmail_draft_delete** — Delete a draft
- **Labels**
- **gmail_labels_list** — List all labels
- **gmail_label_get** — Get a label
- **gmail_label_create** — Create a label
- **gmail_label_update** — Update a label
- **gmail_label_delete** — Delete a label
- **Attachments**
- **gmail_attachment_get** — Download attachment
- **Filters**
- **gmail_filters_list** — List email filters
- **gmail_filter_get** — Get a filter
- **gmail_filter_create** — Create a filter
- **gmail_filter_delete** — Delete a filter
- **Settings**
- **gmail_vacation_get** — Get vacation auto-reply settings
- **gmail_vacation_set** — Set vacation auto-reply settings

## Claude Desktop Quick Installation
No confirmed install details yet, so no config is published. Follow the setup steps in the repository above.

## Documentation

## What the Gmail MCP server does

The Gmail MCP server exposes Gmail account and mailbox operations through MCP. Agents can retrieve the signed-in user's profile, search messages or threads, read individual messages, and inspect every message in a thread. Thread search and retrieval are identified as the preferred options when working with conversations.

Email-management operations include sending messages, forwarding messages, applying or removing labels, archiving inbox items, moving messages or threads to trash, restoring them, and permanently deleting them. Batch message operations support bulk label changes and permanent deletion.

Draft workflows cover listing, reading, creating, updating, sending, and deleting drafts. The server also exposes label listing and retrieval, along with additional Gmail operations documented by the project for attachments, filters, and vacation auto-reply settings.

## How it works

The Gmail MCP server acts as an OAuth proxy between an MCP client and Google. The client connects to the MCP endpoint, while the server advertises OAuth authorization metadata, registers clients, redirects users to Google, and handles the callback and token exchange. Authenticated requests arriving at `/mcp` are sent to the Gmail API with the bearer token.

The documented architecture says the server does not retain tokens or application state; it passes OAuth traffic between the client and Google. Gmail API access is based on scopes for reading, sending, and modifying mailbox content. Modification access covers actions such as archiving, changing labels, and moving messages to trash.

## Setup and configuration

Create a Google Cloud project or use an existing one, enable the Gmail API, configure the OAuth consent screen, and create an OAuth client ID for a web application. Add `http://localhost:3000/callback` as an authorized redirect URI, then retain the generated client ID and client secret.

Start the server with the Google credentials and HTTP transport configured:

```bash
GOOGLE_CLIENT_ID='your-client-id' \
GOOGLE_CLIENT_SECRET='your-client-secret' \
MCP_TRANSPORT=http \
npm start
```

The default address is `http://localhost:3000`. Set `PORT` to use another port, such as `3001`. Once it is running, use the project's installation instructions to generate MCP client configuration for the server endpoint.

## Tools and capabilities

- Search and list messages or threads.
- Read messages and complete threads.
- Send, forward, create, update, and send drafts.
- Add or remove labels, archive messages, and perform bulk label changes.
- Trash, restore, or permanently delete messages and threads.
- List and inspect Gmail labels.
- Retrieve attachments and manage documented filters and vacation settings.

## Limitations and notes

The server requires Google OAuth credentials and Gmail API access. Actions that change mailbox content need the corresponding Gmail modification scope, while sending requires the send scope. Permanent deletion and sending are available as separate tools, so an agent configuration should account for their different effects.

The message-listing tool is available, but the project recommends thread listing for conversation-oriented searches. Likewise, thread retrieval is recommended when the agent needs the complete conversation rather than one message.

The provided setup uses a localhost callback and HTTP transport.

_Full upstream README: https://allmcps.com/mcp/gmail/readme_