You can use the Gmail AutoAuth MCP Server to manage Gmail from Claude Desktop through natural language interactions. It handles sending, reading, searching, listing, and organizing emails via Gmail's API with a streamlined authentication flow that can auto-launch a browser for OAuth. This enables you to control Gmail tasks from your MCP-enabled client with minimal setup.

How to use

You will connect to the Gmail AutoAuth MCP Server from your MCP client (such as Claude Desktop) by configuring a local or remote MCP instance. Once connected, you can ask it to send emails with attachments, read messages by ID, search messages with criteria, list emails from inbox or specific labels, mark emails as read or unread, move emails between labels, and delete emails. The server handles authentication with Google via OAuth 2.0 and stores credentials securely on your machine for persistent access. Use the available commands through natural language prompts like “Send an email to …” or “Show my unread emails in the Inbox.” It will perform the requested Gmail operations and return results in your MCP client's interface.

To authenticate, you can use the global authentication flow, which stores credentials in a global config, or perform local authentication from your current working directory. The authentication flow opens your browser to complete Google sign-in and then saves the credentials for future use. After authentication, you can reuse the credentials from any directory on your machine.

How to install

Prerequisites you need:
- Node.js installed on your machine (to run npx and npm packages)
- Optional: Docker if you prefer containerized usage
- Access to Google Cloud Console to create OAuth 2.0 credentials for Gmail API access

Step 1: Install the MCP server locally or via a package manager
- If you want to install via the package manager, run the following:

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

- For manual setup, you will prepare Google OAuth credentials as described below and then authenticate.

Step 2: Prepare Google Cloud OAuth credentials

• Create a Google Cloud Project and enable Gmail API
• Create OAuth 2.0 credentials (Desktop app or Web application)
• For Web applications, add http://localhost:3000/oauth2callback to the authorized redirect URIs
• Download the JSON key file and rename it to gcp-oauth.keys.json

Step 3: Run authentication (choose global or local) 
Global authentication (recommended):

First time: Put gcp-oauth.keys.json in your home directory

mkdir -p ~/.gmail-mcp mv gcp-oauth.keys.json ~/.gmail-mcp/

Run authentication from anywhere

npx @gongrzhe/server-gmail-autoauth-mcp auth

Local authentication:

Put gcp-oauth.keys.json in the current directory

The file will be copied to the global config automatically

npx @gongrzhe/server-gmail-autoauth-mcp auth

- The process will look for gcp-oauth.keys.json in the current directory or ~/.gmail-mcp/
- It will open your browser for Google authentication and save credentials to ~/.gmail-mcp/credentials.json
- Credentials are stored globally and can be reused from any directory

Claude Desktop configuration

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": [
        "@gongrzhe/server-gmail-autoauth-mcp"
      ]
    }
  }
}

Docker support

If you prefer running the server in a container, you can authenticate via Docker and then run the server container with the appropriate environment paths for credentials.

# Authentication via Docker (example)
docker run -i --rm \
  --mount type=bind,source=/path/to/gcp-oauth.keys.json,target=/gcp-oauth.keys.json \
  -v mcp-gmail:/gmail-server \
  -e GMAIL_OAUTH_PATH=/gcp-oauth.keys.json \
  -e "GMAIL_CREDENTIALS_PATH=/gmail-server/credentials.json" \
  -p 3000:3000 \
  mcp/gmail auth

# Start the server container (example)
docker run -i --rm \
  -v mcp-gmail:/gmail-server \
  -e GMAIL_CREDENTIALS_PATH=/gmail-server/credentials.json \
  mcp/gmail

Security notes

OAuth credentials are stored securely in your local environment under ~/.gmail-mcp/. The server uses offline access to maintain persistent authentication. Never share or commit credentials to version control. Regularly review and revoke unused access in your Google Account settings. Credentials are stored locally but are accessible only to the current user.

Troubleshooting

OAuth Keys Not Found: Ensure gcp-oauth.keys.json is in your current directory or in ~/.gmail-mcp/. Check file permissions.

Invalid Credentials Format: Ensure the OAuth keys file contains web or installed credentials and that the redirect URI is configured correctly for web apps.

Port conflicts: If port 3000 is in use, free it up before authentication. Identify and stop the conflicting process.

Notes on configuration and usage

The server supports a range of Gmail operations through simple prompts. Typical actions include sending messages, reading messages by ID, searching with criteria, listing messages from labels, and updating message labels. Authentication credentials are stored locally and reused automatically, minimizing repeated sign-ins.

Examples of capabilities

• Send emails with subject, content, and recipients
• Read email messages by ID
• Search emails by sender, subject, or date range
• List emails in Inbox, Sent, or custom labels
• Mark emails as read/unread
• Move emails between labels/folders
• Delete emails
• Auto-authenticate with Gmail API via OAuth 2.0

Available tools

sendEmail

Send an email with specified recipients, subject, body, and optional attachments.

readEmail

Read an email by its message ID and return its content and metadata.

searchEmails

Search emails using criteria such as sender, subject, and date range.

listEmails

List emails in a specific mailbox like INBOX or a labeled folder.

markRead

Mark a message as read or unread.

moveEmail

Move a message to a different label or folder.

deleteEmail

Delete an email by ID.

authFlow

OAuth 2.0 authentication flow with optional global or local configuration and credential storage.