@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

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

2. Enable the Gmail API

1. Navigate to APIs & Services → Library
2. Search for "Gmail API"
3. Click Enable

3. Create OAuth2 Credentials

1. Navigate to APIs & Services → Credentials
2. Click Create Credentials → OAuth client ID
3. 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
4. Application type: Web application
5. Add https://developers.google.com/oauthplayground as an authorized redirect URI
6. Save your Client ID and Client Secret

4. Get a Refresh Token

1. Go to Google OAuth2 Playground
2. Click the ⚙️ gear icon (top right) and check Use your own OAuth credentials
3. Enter your Client ID and Client Secret
4. In the left panel, find Gmail API v1 and select https://mail.google.com/
5. Click Authorize APIs and grant access
6. Click Exchange authorization code for tokens
7. 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