Safe Gmail MCP

A security-hardened Gmail MCP server for Claude Code. Supports reading, labeling, archiving, and drafting emails - but cannot send or delete.

Quick Start

git clone <this-repo>
cd safe-gmail-mcp
npm install
npm run init

The setup wizard will guide you through:

1. Creating Google Cloud OAuth credentials
2. Authenticating with your Gmail account
3. Configuring Claude Code

Why This Exists

The original Gmail MCP has powerful capabilities that could be dangerous if misused:

• Send emails (impersonation risk)
• Delete emails (data loss)
• Create filters (auto-forward/delete)

This fork removes those dangerous operations while keeping everything needed for email triage workflows.

What You Can Do

| Tool | Description | |------|-------------| | draft_email | Create a draft email (you send manually) | | send_email | Send email to yourself only (for reminders) | | read_email | Read email content by ID | | search_emails | Search with Gmail syntax | | list_email_labels | List all labels | | create_label | Create a new label | | update_label | Update a label | | delete_label | Delete a user-created label | | get_or_create_label | Get existing or create new label | | modify_email | Add/remove labels from an email | | batch_modify_emails | Bulk label modifications | | download_attachment | Save attachment to disk |

What You CANNOT Do

• Send emails to others (only drafts)
• Delete emails
• Create filters

Commands

| Command | Description | |---------|-------------| | npm run init | Interactive setup wizard | | npm run auth | Re-authenticate (if token expires) | | npm run status | Check authentication status | | npm start | Run the MCP server |

Manual Setup

If you prefer not to use the wizard:

1. Create Google Cloud OAuth Credentials

1. Go to Google Cloud Console
2. Create a new project
3. Enable the Gmail API: APIs & Services > Library > Gmail API > Enable
4. Configure OAuth consent screen:
   • User type: External
   • Add your email as a test user
5. Create credentials: Credentials > Create > OAuth Client ID > Desktop app
6. Download the JSON file

2. Set Up Credentials

mkdir -p ~/.safe-gmail-mcp
chmod 700 ~/.safe-gmail-mcp
mv ~/Downloads/client_secret_*.json ~/.safe-gmail-mcp/gcp-oauth.keys.json
chmod 600 ~/.safe-gmail-mcp/gcp-oauth.keys.json

3. Authenticate

npm run auth

4. Configure Claude Code

Add to your .mcp.json:

{
  "mcpServers": {
    "safe-gmail": {
      "command": "node",
      "args": ["/path/to/safe-gmail-mcp/src/index.js"],
      "env": {
        "GMAIL_OAUTH_PATH": "/Users/you/.safe-gmail-mcp/gcp-oauth.keys.json",
        "GMAIL_CREDENTIALS_PATH": "/Users/you/.safe-gmail-mcp/credentials.json"
      }
    }
  }
}

Troubleshooting

"Gmail API has not been used"

Enable Gmail API: APIs & Services > Library > Gmail API > Enable

"Access denied" or 403 error

Add your email as a test user in the OAuth consent screen.

Token expired

Run npm run auth to re-authenticate.

Port already in use

The auth flow tries ports 3000, 3001, 3002. Close any apps using these ports.

Security

See SECURITY.md for detailed security design documentation.

License

ISC (inherited from original project)

Credits

Fork of @gongrzhe/server-gmail-autoauth-mcp