Gmail MCP Server

How to use

Install and run the Gmail MCP Server, then connect it to your MCP client (for example Claude Desktop). You can operate by asking the client to send emails, read conversations, search mail, manage drafts and labels, or save attachments. The server handles threading, time zone differences, and supports multi-account sending along with category filtering (Primary, Social, Promotions, etc.). Set an attachment folder and time zone so all operations align with your environment.

How to install

Prerequisites: you need Node.js and npm installed on your machine. You will also use a Google Cloud OAuth credential file for Gmail access.

# Option 1: Quick start using NPX
npx @cristip73/email-mcp

# Authenticate for first-time setup
npx @cristip73/email-mcp auth

# Optional: if you want to run the server locally with a local setup later, see Option 2 below

Option 1: Using NPX (Recommended)

Run the MCP Email Server directly with NPX without installing it globally, then authenticate.

npx @cristip73/email-mcp
```

```bash
npx @cristip73/email-mcp auth

Option 2: Clone and Install Locally

If you prefer a local setup, clone the repository, install dependencies, build, authenticate, and link the package so Claude can access it.

# 1) Clone the project
git clone https://github.com/cristip73/MCP-email-server.git
cd MCP-email-server

# 2) Install dependencies
npm install

# 3) Build the server
npm run build

# 4) Authenticate with Gmail (opens a browser for sign-in)
npm run auth

# 5) Make the package available to Claude
npm link

Setting up Google Cloud OAuth Credentials

Before using the server, configure OAuth credentials in Google Cloud and download the credentials file.

1) Go to Google Cloud Console
2) Create or select a project
3) APIs & Services > Library, enable Gmail API
4) APIs & Services > Credentials, Create Credentials > OAuth client ID
5) Choose Desktop application, name it (e.g., "MCP Email Client")
6) Download the credentials JSON file
7) Rename to gcp-oauth.keys.json
8) Place it in either the current working directory or in ~/.email-mcp/gcp-oauth.keys.json

Usage with Claude

To use the MCP server with Claude Desktop, add the MCP server by editing the Claude configuration file and pointing to the NPX-based start command. The server runs through NPX and can be started by Claude when you restart the app.

{
  "mcpServers": {
    "email-server": {
      "command": "npx",
      "args": [
        "-y",
        "@cristip73/email-mcp"
      ],
      "env": {
          "TIME_ZONE": "GMT+2",
          "DEFAULT_ATTACHMENTS_FOLDER": "/Users/username/CLAUDE/Attachments"
      }     
    }
  }
}

Claude Code Editor setup

For Claude Code Editor, you can add the server with a direct command, pointing to the built index if you compile locally.

claude mcp add email-server -- /path/to/email-server/build/index.js

send_email

Send a new email, including CC, BCC and attachments.

reply_all_email

Reply to an email including all original recipients, excluding your own address to prevent self-replies.

forward_email

Forward an email to new recipients with original headers and threading preserved.

list_send_as_accounts

List all accounts and send-as addresses available for composing messages.

get_recent_emails

Fetch recent emails with optional time filters, categories, and pagination.

read_email

Read a specific email by ID and extract content and attachments.

search_emails

Search emails using Gmail query syntax with category and time filters.

list_labels

List all labels in the mailbox.

get_label

Retrieve details about a specific label by ID.

create_label

Create a new label with visibility and color options.

update_label

Update label properties such as name, visibility and color.

delete_label

Delete a label from the mailbox.

modify_labels

Add or remove labels from a message.

mark_as_read

Mark a message as read.

mark_as_unread

Mark a message as unread.

archive_message

Archive a message (remove from inbox).

unarchive_message

Unarchive a message back to the inbox.

trash_message

Move a message to trash.

create_draft

Create a new draft email without sending it.

get_draft

Retrieve a specific draft by ID.

list_drafts

List drafts with optional pagination and filtering.

update_draft

Modify an existing draft content.

delete_draft

Delete a draft from the account.

send_draft

Send a saved draft.

get_timezone_info

Display the currently configured timezone details.

list_attachments

List attachments within an email and their metadata.

save_attachment

Save an attachment from an email to the configured folder with path validation.