custom-gmail-mcp

An MCP (Model Context Protocol) server that lets Claude and other AI assistants access your Gmail inbox. Includes a React GUI accessible via a browser.

Features

• List, search and read emails
• Send emails and create drafts
• Manage labels and threads
• Mark messages as read/unread, move to trash
• React-based GUI for visual browsing
• OAuth2 authentication with automatic token refresh

Prerequisites

• Node.js >= 18
• A Google Cloud project with the Gmail API enabled
• OAuth 2.0 credentials (Client ID + Client Secret)

Installation & Setup

1. Create your config file

Create the directory ~/.config/custom-gmail-mcp/ and add a .env file:

GOOGLE_CLIENT_ID=your_client_id_here
GOOGLE_CLIENT_SECRET=your_client_secret_here

# Optional
GUI_PORT=3002
PROXY_URL=http://localhost:3000
PROXY_APP_PATH=/custom-gmail-mcp
PROXY_APP_NAME=Custom Gmail MCP

# Docker / custom redirect URI (overrides PROXY_URL+PROXY_APP_PATH)
# OAUTH_CALLBACK_BASE_URL=http://localhost:3002

The redirect URI sent to Google is built with the following priority:

| Scenario | redirect_uri | |---|---| | OAUTH_CALLBACK_BASE_URL set | {OAUTH_CALLBACK_BASE_URL}/oauth2callback | | PROXY_URL + PROXY_APP_PATH set | {PROXY_URL}{PROXY_APP_PATH}/oauth2callback | | Default | http://localhost:{GUI_PORT}/oauth2callback |

Declare the corresponding URL as an Authorized redirect URI in the Google Cloud Console.

Note on OAuth verification: Gmail scopes require app verification for production. In development, add your email as a "test user" in the OAuth consent screen.

2. Authenticate

npx custom-gmail-mcp-setup

This opens a browser OAuth flow and saves your tokens to ~/.config/custom-gmail-mcp/tokens.json.

3. Configure your MCP client (Claude Desktop / Cursor)

{
  "mcpServers": {
    "custom-gmail-mcp": {
      "command": "npx",
      "args": ["-y", "custom-gmail-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "your_client_id_here",
        "GOOGLE_CLIENT_SECRET": "your_client_secret_here",
        "GUI_PORT": "3002"
      }
    }
  }
}

Available Tools

| Tool | Description | |---|---| | list_messages | List emails (optional Gmail search query) | | get_message | Get the full content of an email by ID | | search_messages | Search emails with Gmail syntax | | list_labels | List all Gmail labels and folders | | get_thread | Get a complete email thread | | send_email | Send an email | | create_draft | Create a draft email | | trash_message | Move an email to trash | | mark_as_read | Mark an email as read | | mark_as_unread | Mark an email as unread |

Development

git clone <repo>
cd gmail-mcp
npm install
npm run install:gui
npm run build

License

ISC