@gongrzhe/server-gmail-mcp

v0.0.8

Published

5 months ago

Gmail MCP server with auto authentication support

Downloads

0High
0Medium
0Low

gongrzhe

gmail mcp cursor ai oauth model-context-protocol google-gmail claude auto-auth

Gmail MCP Server

A Model Context Protocol (MCP) server for Gmail integration with comprehensive email management capabilities, attachments support, and OAuth2 authentication.

Features

Email Operations: Send, draft, read, search, modify, and delete emails
Attachment Support: Full support for sending and receiving file attachments
Label Management: Create, update, delete, and manage Gmail labels
Batch Operations: Process multiple emails efficiently in batches
OAuth2 Authentication: Secure authentication with auto browser launch
Multiple Transport Modes: Stdio, HTTP (Streamable), and SSE support
Session Management: Complete multi-user isolation and session-aware architecture

Quick Start

Starting the Server

# Start HTTP server on port 3000 (default)
node dist/index.js --http

# Start HTTP server on custom port
PORT=8080 node dist/index.js --http

# Start in stdio mode
node dist/index.js

The server provides these endpoints:

POST /mcp - Main MCP endpoint
GET /health - Health check with session statistics
GET /sessions - Session management information

Authentication

All requests require a Gmail OAuth2 access token via Authorization header:

Authorization: Bearer ya29.your_oauth_token_here

Set up Gmail API credentials and obtain OAuth2 tokens with the following scopes:

https://www.googleapis.com/auth/gmail.modify
https://www.googleapis.com/auth/gmail.readonly

Tools

The server provides 14 tools for comprehensive Gmail API access. Each tool requires Authorization: Bearer <token> header.

1. send_email

Send an email using Gmail API.

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your_oauth_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
      "name": "send_email",
      "arguments": {
        "to": ["[email protected]"],
        "subject": "Test Email",
        "body": "Hello from Gmail MCP Server!",
        "mimeType": "text/plain"
      }
    }
  }'

2. draft_email

Create a draft email.

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your_oauth_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "2",
    "method": "tools/call",
    "params": {
      "name": "draft_email",
      "arguments": {
        "to": ["[email protected]"],
        "subject": "Draft Email",
        "body": "This is a draft email",
        "htmlBody": "<p>This is a <b>draft</b> email</p>",
        "mimeType": "multipart/alternative"
      }
    }
  }'

3. read_email

Retrieve the content of a specific email.

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your_oauth_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "3",
    "method": "tools/call",
    "params": {
      "name": "read_email",
      "arguments": {
        "messageId": "1234567890abcdef"
      }
    }
  }'

4. search_emails

Search for emails using Gmail search syntax.

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your_oauth_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "4",
    "method": "tools/call",
    "params": {
      "name": "search_emails",
      "arguments": {
        "query": "from:[email protected] is:unread",
        "maxResults": 10
      }
    }
  }'

5. modify_email

Modify email labels (move to different folders).

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your_oauth_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "5",
    "method": "tools/call",
    "params": {
      "name": "modify_email",
      "arguments": {
        "messageId": "1234567890abcdef",
        "addLabelIds": ["IMPORTANT"],
        "removeLabelIds": ["UNREAD"]
      }
    }
  }'

6. delete_email

Permanently delete an email.

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your_oauth_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "6",
    "method": "tools/call",
    "params": {
      "name": "delete_email",
      "arguments": {
        "messageId": "1234567890abcdef"
      }
    }
  }'

7. list_email_labels

Retrieve all available Gmail labels.

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your_oauth_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "7",
    "method": "tools/call",
    "params": {
      "name": "list_email_labels",
      "arguments": {}
    }
  }'

8. batch_modify_emails

Modify labels for multiple emails in batches.

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your_oauth_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "8",
    "method": "tools/call",
    "params": {
      "name": "batch_modify_emails",
      "arguments": {
        "messageIds": ["1234567890abcdef", "fedcba0987654321"],
        "addLabelIds": ["IMPORTANT"],
        "batchSize": 50
      }
    }
  }'

9. batch_delete_emails

Permanently delete multiple emails in batches.

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your_oauth_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "9",
    "method": "tools/call",
    "params": {
      "name": "batch_delete_emails",
      "arguments": {
        "messageIds": ["1234567890abcdef", "fedcba0987654321"],
        "batchSize": 50
      }
    }
  }'

10. create_label

Create a new Gmail label.

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your_oauth_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "10",
    "method": "tools/call",
    "params": {
      "name": "create_label",
      "arguments": {
        "name": "My Custom Label",
        "messageListVisibility": "show",
        "labelListVisibility": "labelShow"
      }
    }
  }'

11. update_label

Update an existing Gmail label.

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your_oauth_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "11",
    "method": "tools/call",
    "params": {
      "name": "update_label",
      "arguments": {
        "id": "Label_123456",
        "name": "Updated Label Name",
        "messageListVisibility": "hide"
      }
    }
  }'

12. delete_label

Delete a Gmail label.

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your_oauth_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "12",
    "method": "tools/call",
    "params": {
      "name": "delete_label",
      "arguments": {
        "id": "Label_123456"
      }
    }
  }'

13. get_or_create_label

Get an existing label by name or create it if it doesn't exist.

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your_oauth_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "13",
    "method": "tools/call",
    "params": {
      "name": "get_or_create_label",
      "arguments": {
        "name": "Project Alpha",
        "messageListVisibility": "show",
        "labelListVisibility": "labelShow"
      }
    }
  }'

14. download_attachment

Download an email attachment.

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your_oauth_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "14",
    "method": "tools/call",
    "params": {
      "name": "download_attachment",
      "arguments": {
        "messageId": "1234567890abcdef",
        "attachmentId": "ANGjdJ123456",
        "filename": "document.pdf",
        "savePath": "/path/to/save"
      }
    }
  }'

List Available Tools

Get the complete list of available tools:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your_oauth_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "tools-list",
    "method": "tools/list",
    "params": {}
  }'

Installation & Authentication

Installing via Smithery

To install Gmail AutoAuth for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @gongrzhe/server-gmail-autoauth-mcp --client claude

Manual Installation

Create Google Cloud Project and obtain credentials:
- Go to Google Cloud Console
- Create a new project or select an existing one
- Enable the Gmail API
- Create OAuth2 credentials (Desktop application type)
- Download the credentials file

Install the server:

npm install -g @gongrzhe/server-gmail-mcp

Configure authentication:
- Place your OAuth2 credentials file in a secure location
- The server will automatically launch the browser for OAuth flow
- Tokens are stored securely for future use

Usage with Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": ["/path/to/gmail-mcp/dist/index.js"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/credentials.json"
      }
    }
  }
}

Advanced Features

Session Management

Complete Multi-user Isolation: Each session is completely isolated
Session-aware Architecture: Proper response routing in concurrent environments
Automatic Session Cleanup: Expired sessions are automatically cleaned up

Batch Operations

Efficient Processing: Handle multiple emails in configurable batch sizes
Error Handling: Individual item failures don't stop batch processing
Progress Tracking: Detailed success/failure reporting

Attachment Support

Full MIME Support: Handle complex email structures with nested attachments
Security: Safe attachment processing with proper validation
Metadata: Complete attachment information including size, type, and filename

Health Monitoring

Check server health and session statistics:

curl http://localhost:3000/health

View active sessions:

curl http://localhost:3000/sessions

Error Handling

The server provides comprehensive error handling with specific error codes:

401: Authentication errors (invalid or expired tokens)
403: Permission errors (insufficient OAuth2 scopes)
404: Resource not found errors
500: Internal server errors

Gmail Search Syntax

When using the search_emails tool, you can use Gmail's powerful search syntax:

from:[email protected] - Emails from specific sender
to:[email protected] - Emails to specific recipient
subject:meeting - Emails with "meeting" in subject
has:attachment - Emails with attachments
is:unread - Unread emails
is:important - Important emails
in:inbox - Emails in inbox
label:work - Emails with specific label
after:2023/12/01 - Emails after specific date
before:2023/12/31 - Emails before specific date

Build

npm run build

License

This MCP server is licensed under the ISC License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the ISC License.