@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:

Related MCP server: gmail-mcp

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

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