Gmail MCP Tool for Cline

A Model Context Protocol (MCP) server that provides Gmail integration capabilities for Cline or other MCP-compatible AI assistants.

Overview

This tool allows Cline to interact with your Gmail account to:

1. List and read emails - View emails in your inbox, search for specific messages, and read their contents
2. Draft and send emails - Create drafts, modify them, and send emails on your behalf
3. Organize your inbox - Apply labels, move messages between folders, and set up filtering rules

Architecture

The Gmail MCP tool is built using:

• TypeScript - For type-safe development
• MCP SDK - To expose tools and resources to Cline
• Google API Node.js Client - For Gmail API interactions
• OAuth2 Authentication - For secure access to your Gmail account

Gmail API Capabilities

This tool implements the following Gmail API functionalities:

Email Reading & Management

• List emails with filtering options
• Read complete email content
• Apply/remove labels
• Move emails between folders
• Advanced search capability using Gmail's query syntax

Email Composition & Sending

• Create new draft emails
• Update existing drafts
• Send new emails or drafts
• Reply to or forward existing emails

Mail Rules & Automation

• Create and manage labels
• Define filtering rules for incoming mail
• View and modify existing filters

Initial Setup

Prerequisites

1. A Google Cloud Project with the Gmail API enabled
2. OAuth client credentials (client ID and client secret)
3. Node.js and npm installed

Setup Steps

1. Create a Google Cloud Project:

   • Go to Google Cloud Console
   • Create a new project
   • Enable the Gmail API
   • Create OAuth consent screen (External) with your email in test users
   • Create OAuth client credentials (Web application)
   • Download the credentials JSON file

2. Get a refresh token:

   • Run the included script: node scripts/get-refresh-token.js
   • Follow the authentication flow in your browser
   • Copy the refresh token from the output

3. Configure MCP settings:

   • Add the Gmail MCP server configuration to your MCP settings file:

"gmail": {
  "command": "node",
  "args": ["/path/to/gmail-mcp/build/index.js"],
  "env": {
    "GMAIL_CLIENT_ID": "your-client-id",
    "GMAIL_CLIENT_SECRET": "your-client-secret",
    "GMAIL_REFRESH_TOKEN": "your-refresh-token"
  },
  "disabled": false,
  "autoApprove": []
}

Available Tools

The Gmail MCP server provides the following tools for Cline:

Email Reading

• gmail_list_messages - List emails with filtering options
• gmail_get_message - Get detailed content of a specific email
• gmail_search - Search emails with Gmail's query syntax

Email Management

• gmail_modify_message - Apply/remove labels or mark as read/unread
• gmail_trash_message - Move message to trash
• gmail_delete_message - Permanently delete message

Email Composition

• gmail_create_draft - Create a new draft email
• gmail_update_draft - Update an existing draft
• gmail_delete_draft - Delete a draft
• gmail_send_draft - Send an existing draft
• gmail_send_message - Create and send a new email directly

Reply & Forward

• gmail_create_reply - Create a reply to an email
• gmail_create_forward - Create a forward of an email

Label Management

• gmail_list_labels - List all labels in the account
• gmail_create_label - Create a new label
• gmail_delete_label - Delete a label
• gmail_update_label - Modify a label's properties

Filter Management

• gmail_list_filters - List all filters in the account
• gmail_create_filter - Create a new filter
• gmail_delete_filter - Delete a filter

Development

Building from source

# Install dependencies
npm install

# Build the project
npm run build

Project Structure

• src/index.ts - Main MCP server implementation
• src/gmail-client.ts - Gmail API wrapper
• src/tool-definitions.ts - Tool schema definitions
• src/auth-utils.ts - Authentication utilities
• scripts/get-refresh-token.js - OAuth refresh token generation

Privacy and Security

This tool runs locally on your machine and requires OAuth credentials to access your Gmail account. Your email data is never stored outside your control.

It's recommended to:

1. Use a dedicated Google Cloud Project
2. Limit the permissions requested during OAuth
3. Regularly rotate your refresh token

Limitations

• Subject to Gmail API rate limits and quotas
• Complex filtering rules may require multiple operations
• Attachments over a certain size may need special handling

Roadmap

Future enhancements may include:

1. Email template management
2. Scheduled sending capabilities
3. Advanced filtering and organization tools
4. Attachment handling improvements
5. Integration with other Google services (Calendar, Drive)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT