@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