Skip to content
Jefferson Gonçalves
← Back to projects

Mcp Server Gmail

MCP server for Gmail — read, search, send, reply, and manage emails via AI agents

#@franciscpd/gmail-mcp-server

CI npm version License: MIT

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

New version available.