@franciscpd/gmail-mcp-server

A Model Context Protocol (MCP) server for Gmail. Read, search, send, reply, forward emails and manage labels — powered by 3 environment variables.

Quick Start

npx -y @franciscpd/gmail-mcp-server

Set these environment variables:

| Variable | Description | |----------|-------------| | GMAIL_CLIENT_ID | OAuth2 client ID from Google Cloud Console | | GMAIL_CLIENT_SECRET | OAuth2 client secret | | GMAIL_REFRESH_TOKEN | OAuth2 refresh token (see Setup Guide) |

Setup Guide

1. Create a Google Cloud Project

Go to Google Cloud Console
Create a new project (or select an existing one)
Note your project name for the next steps

2. Enable the Gmail API

Navigate to APIs & Services → Library
Search for "Gmail API"
Click Enable

3. Create OAuth2 Credentials

Navigate to APIs & Services → Credentials
Click Create Credentials → OAuth client ID
If prompted, configure the OAuth consent screen:
- User type: External (or Internal for Workspace)
- Add the scope: https://mail.google.com/
- Add your email as a test user
Application type: Web application
Add https://developers.google.com/oauthplayground as an authorized redirect URI
Save your Client ID and Client Secret

4. Get a Refresh Token

Go to Google OAuth2 Playground
Click the ⚙️ gear icon (top right) and check Use your own OAuth credentials
Enter your Client ID and Client Secret
In the left panel, find Gmail API v1 and select https://mail.google.com/
Click Authorize APIs and grant access
Click Exchange authorization code for tokens
Copy the Refresh token

Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": ["-y", "@franciscpd/gmail-mcp-server"],
      "env": {
        "GMAIL_CLIENT_ID": "your-client-id",
        "GMAIL_CLIENT_SECRET": "your-client-secret",
        "GMAIL_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

Cursor

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": ["-y", "@franciscpd/gmail-mcp-server"],
      "env": {
        "GMAIL_CLIENT_ID": "your-client-id",
        "GMAIL_CLIENT_SECRET": "your-client-secret",
        "GMAIL_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

Generic MCP Client

GMAIL_CLIENT_ID=your-client-id \
GMAIL_CLIENT_SECRET=your-client-secret \
GMAIL_REFRESH_TOKEN=your-refresh-token \
npx -y @franciscpd/gmail-mcp-server

The server communicates over stdio using the MCP protocol.

Tools

| Tool | Description | |------|-------------| | gmail_read_emails | List emails from a label with pagination | | gmail_get_email | Get full email content by ID | | gmail_search_emails | Search with Gmail query syntax | | gmail_get_thread | Get all messages in a thread | | gmail_get_attachment | Download attachment by ID | | gmail_send_email | Compose and send a new email | | gmail_reply_email | Reply to an email in-thread | | gmail_forward_email | Forward an email to new recipients | | gmail_list_labels | List all labels with counts | | gmail_modify_labels | Batch add/remove labels |

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Start the server
npm start

License

MIT

MCP Servers