shubhiscoding/Gmail-MCP-Server

Gmail MCP Server

A Model Context Protocol (MCP) server for Gmail integration, built with FastMCP. This server provides AI assistants with the ability to interact with Gmail through a set of standardized tools.

Overview

This project implements an MCP server that allows AI assistants to perform various Gmail operations including:

• Fetching emails from your inbox
• Searching emails by subject
• Searching emails from specific senders
• Retrieving unread emails
• Sending emails to recipients

The server uses IMAP for email retrieval and SMTP for sending emails, all secured through Gmail's authentication system.

Setup

1. Clone the repository

git clone https://github.com/shubhiscoding/Gmail-MCP-Server
cd gmail-mcp

2. Install dependencies

npm install

3. Create a .env file in the root directory with the following variables:

GMAIL_USER=your_gmail_address
GMAIL_APP_PASSWORD=your-app-password

To generate an App Password for your Gmail account:

1. Go to your Google Account > Security
2. Enable 2-Step Verification if not already enabled
3. Go to App passwords
4. Select "Mail" and your device
5. Click "Generate"

Usage

Starting the Server

Start the server in development mode:

npm run dev

Configuration to run with Windsurf

Configure mcp_config.json to add gmail-mcp server:

{
  "mcpServers": {
    "gmail-mcp": {
      "command": "bash",
      "args": [
        "-c",
        "cd ~Your-Path-To-The-Repo/Gmail-MCP-Server && npm run start"
      ],
      "disabled": false
    }
  }
}

Configuration to run with Claude desktop on Windows

{
  "mcpServers": {
    "gmail-mcp": {
      "command": "cmd",
      "args": ["/c", "cd /d ~Your-Path-To-The-Repo\\Gmail-MCP-Server && npm run start"]
    }
  }
}

Video Demo

Windsruf demo

https://github.com/user-attachments/assets/0c45ec24-be45-4271-b7d0-fc6cd58b850f

Claude Desktop Demo

https://github.com/user-attachments/assets/ad1650e8-bcc4-481e-ab95-eaefd8de7472

Available Tools

The server provides the following tools for AI assistants:

1. fetchEmails

Fetches emails from your inbox with optional filtering.

Parameters:

• limit (optional): Maximum number of emails to fetch (default: 10)
• mailbox (optional): Mailbox to fetch emails from (default: 'INBOX')
• searchCriteria (optional): IMAP search criteria (default: ['ALL'])

2. fetchEmailsBySubject

Fetches emails with a specific subject.

Parameters:

• subject: Subject to search for
• limit (optional): Maximum number of emails to fetch (default: 10)

3. fetchEmailsFromSender

Fetches emails from a specific sender.

Parameters:

• sender: Email address of the sender
• limit (optional): Maximum number of emails to fetch (default: 10)

4. fetchUnreadEmails

Fetches unread emails from your inbox.

Parameters:

• limit (optional): Maximum number of emails to fetch (default: 10)

5. sendEmails

Sends an email to a specified recipient.

Parameters:

• to: Email address of the recipient
• subject: Subject of the email
• body: Body of the email

Security

This server uses environment variables to store sensitive information like your Gmail credentials. Never commit your .env file to version control.

Technical Details

The project is built with:

• TypeScript for type safety
• Node.js IMAP and Nodemailer libraries for email operations
• FastMCP for MCP server implementation
• dotenv for environment variable management