Gmail Sender MCP Server

An MCP (Model Context Protocol) server that enables sending emails and creating drafts through the Gmail API.

Features

• sendEmail: Send emails through your Gmail account with optional file attachments
• createDraft: Create email drafts with optional file attachments
• OAuth 2.0 authentication with Google
• Support for file attachments of various types (PDF, DOC, images, etc.)
• Run anywhere with npx - no local installation required

Prerequisites

• Node.js v18 or higher
• A Google Cloud project with Gmail API enabled
• OAuth 2.0 credentials (Client ID and Client Secret)

Setting up Google Cloud Credentials

1. Go to the Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Gmail API for your project
4. Go to Credentials and create an OAuth 2.0 Client ID
5. Set the application type to Web application
6. Add http://localhost:3500/oauth2callback as an authorized redirect URI
7. Save your Client ID and Client Secret

Installation & Usage

Run with npx (Recommended)

The easiest way to use this server is with npx. No installation required:

GMAIL_CLIENT_ID=your_client_id GMAIL_CLIENT_SECRET=your_client_secret npx gmail-sender-mcp-server

Install Globally

npm install -g gmail-sender-mcp-server

Then run:

GMAIL_CLIENT_ID=your_client_id GMAIL_CLIENT_SECRET=your_client_secret gmail-sender-mcp-server

Install Locally (for development)

git clone <repository-url>
cd Gmail_MCP_server
npm install
GMAIL_CLIENT_ID=your_client_id GMAIL_CLIENT_SECRET=your_client_secret npm start

Authentication

On first run, the server will start an OAuth server on port 3500:

1. Visit http://localhost:3500/auth in your browser
2. Sign in with your Google account and grant permissions
3. The authentication token will be saved to ~/.config/gmail-sender-mcp-server/token.json

The token is stored in your home directory, so it persists across npx runs and works across different machines once authenticated.

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | GMAIL_CLIENT_ID | Yes | Your Google OAuth 2.0 Client ID | | GMAIL_CLIENT_SECRET | Yes | Your Google OAuth 2.0 Client Secret |

MCP Configuration

To use this server with an MCP client (like Claude Desktop), add it to your MCP configuration:

{
  "mcpServers": {
    "gmail-sender": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "gmail-sender-mcp-server"],
      "env": {
        "GMAIL_CLIENT_ID": "your_client_id",
        "GMAIL_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Note: The env block passes values as literal strings — shell command substitution (e.g. $(pass show ...)) will not be evaluated. If you use a secrets manager like pass for your client secret, use bash -c instead:

{
  "mcpServers": {
    "gmail-sender": {
      "type": "stdio",
      "command": "bash",
      "args": [
        "-c",
        "GMAIL_CLIENT_SECRET=$(pass show your/client_secret) npx -y gmail-sender-mcp-server"
      ],
      "env": {
        "GMAIL_CLIENT_ID": "your_client_id"
      }
    }
  }
}

Available Tools

sendEmail

Send an email immediately through Gmail.

Parameters:

• recipient (required): Email address of the recipient
• subject (required): Subject line of the email
• body (required): Body content of the email (plain text)
• attachmentPath (optional): Absolute path to a file to attach

Example:

{
  "recipient": "[email protected]",
  "subject": "Hello from MCP",
  "body": "This is a test email sent via the Gmail MCP server.",
  "attachmentPath": "/path/to/document.pdf"
}

createDraft

Create an email draft in Gmail (not sent automatically).

Parameters:

• recipient (required): Email address of the recipient
• subject (required): Subject line of the email
• body (required): Body content of the email (plain text)
• attachmentPath (optional): Absolute path to a file to attach

Example:

{
  "recipient": "[email protected]",
  "subject": "Draft Email",
  "body": "This is a draft that can be reviewed and sent later.",
  "attachmentPath": "/path/to/image.png"
}

Supported Attachment Types

The server automatically detects file types based on extension:

• Documents: PDF, DOC, DOCX, TXT
• Images: JPG, JPEG, PNG, GIF
• Archives: ZIP
• Other files are sent as application/octet-stream

OAuth Scopes

The server uses the https://www.googleapis.com/auth/gmail.compose scope, which allows:

• Creating and sending emails
• Creating drafts
• Modifying drafts

File Structure

gmail-sender-mcp-server/
├── src/
│   └── index.js          # Main server implementation
├── package.json          # Dependencies and scripts
└── README.md             # This file

~/.config/gmail-sender-mcp-server/
└── token.json            # OAuth tokens (created after authentication)

Security Notes

• OAuth tokens are stored in ~/.config/gmail-sender-mcp-server/token.json and should be kept secure
• Client ID and Secret should be passed via environment variables, not committed to version control
• The OAuth server only runs on localhost (port 3500)
• Consider using a secrets manager for production deployments

Troubleshooting

Authentication Issues

• Ensure your OAuth client is configured with http://localhost:3500/oauth2callback as a redirect URI
• Check that the Gmail API is enabled in your Google Cloud project
• Verify your GMAIL_CLIENT_ID and GMAIL_CLIENT_SECRET environment variables are set correctly

Token Issues

• If authentication fails, delete ~/.config/gmail-sender-mcp-server/token.json and re-authenticate
• Tokens may expire; re-authenticate if you get authorization errors

File Attachment Issues

• Use absolute paths for attachments
• Ensure the file exists and is readable
• Check that the file size is within Gmail's limits (25MB for attachments)

License

MIT

Gmail_MCP_server