vincent-deng/gmail-mcp-server

Gmail MCP Server

A Model Context Protocol (MCP) server for Gmail integration that enables AI assistants like Gemini CLI to draft, send, and manage emails through natural language interactions.

Features

• Draft Emails: Create draft emails with recipients, subject, and body
• Send Emails: Send emails directly through Gmail
• List Drafts: View all draft emails in your account
• Get Draft: Retrieve specific draft content by ID
• Delete Draft: Remove draft emails
• OAuth2 Authentication: Secure authentication with Google APIs

Setup Instructions

1. Install Dependencies

npm install

2. Create Google Cloud Project and Enable Gmail API

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Gmail API:
   • Go to "APIs & Services" > "Library"
   • Search for "Gmail API" and enable it
4. Create OAuth 2.0 credentials:
   • Go to "APIs & Services" > "Credentials"
   • Click "Create Credentials" > "OAuth client ID"
   • Choose "Desktop application"
   • Download the credentials as JSON

3. Configure Credentials

1. Rename the downloaded file to credentials.json
2. Place it in the project root directory
3. Update the redirect URI in Google Cloud Console:
   • Edit your OAuth client
   • Add http://localhost:3000/callback to "Authorized redirect URIs"

4. Authenticate

Run the authentication setup script:

node setup-auth.js

This will:

• Open a browser window for Google OAuth
• Redirect to a local callback server
• Save the refresh token to token.json

5. Test the Server

Start the MCP server:

npm start

Usage with Gemini CLI

Add this server to your MCP client configuration. For Gemini CLI or Claude Desktop, add to your config file:

{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": ["/path/to/your/gmail-mcp-server/index.js"]
    }
  }
}

Available Tools

draft_email

Create a draft email in Gmail.

Parameters:

• to (required): Recipient email address
• subject (required): Email subject
• body (required): Email body content
• cc (optional): CC recipients
• bcc (optional): BCC recipients

send_email

Send an email directly via Gmail.

Parameters:

• to (required): Recipient email address
• subject (required): Email subject
• body (required): Email body content
• cc (optional): CC recipients
• bcc (optional): BCC recipients

list_drafts

List all draft emails.

Parameters:

• maxResults (optional): Maximum number of drafts to return (default: 10)

get_draft

Get a specific draft email by ID.

Parameters:

• draftId (required): Draft ID to retrieve

delete_draft

Delete a draft email by ID.

Parameters:

• draftId (required): Draft ID to delete

Example Usage

Once configured with Gemini CLI, you can use natural language commands like:

• "Draft an email to with subject 'Meeting Tomorrow' and body 'Hi John, let's meet at 3 PM tomorrow.'"
• "Send an email to about the project update"
• "Show me my draft emails"
• "Delete the draft with ID xyz123"

Security Notes

• Keep your credentials.json and token.json files secure
• Never commit these files to version control
• The server only accesses your Gmail account with the permissions you explicitly grant
• Tokens are stored locally and not transmitted to any external services

Requirements

• Node.js 18.0.0 or higher
• Gmail account with API access
• Google Cloud Project with Gmail API enabled

License

MIT