Gmail MCP Server

A Model Context Protocol (MCP) server that provides read-only access to Gmail. Allows Claude Code to safely search, read, and analyze your Gmail inbox.

Features

• search_emails - Search using Gmail query syntax
• list_unread - List unread emails
• get_message - Get full message content with attachments metadata
• get_thread - Get all messages in a conversation thread
• draft_reply - Prepare draft reply content (does NOT send)

Prerequisites

• Node.js 18+
• A Google Cloud project with Gmail API enabled
• OAuth 2.0 Desktop App credentials

Google Cloud Setup

1. Create a Google Cloud Project

1. Go to Google Cloud Console
2. Click "Select a project" → "New Project"
3. Name your project (e.g., "Gmail MCP Server")
4. Click "Create"

2. Enable Gmail API

1. In your project, go to "APIs & Services" → "Library"
2. Search for "Gmail API"
3. Click on it and press "Enable"

3. Configure OAuth Consent Screen

1. Go to "APIs & Services" → "OAuth consent screen"
2. Select "External" (or "Internal" if using Google Workspace)
3. Fill in the required fields:
   • App name: "Gmail MCP Server"
   • User support email: your email
   • Developer contact: your email
4. Click "Save and Continue"
5. Add scopes:
   • https://www.googleapis.com/auth/gmail.readonly
   • https://www.googleapis.com/auth/gmail.compose
6. Add your email as a test user (if External)
7. Complete the setup

4. Create OAuth Credentials

1. Go to "APIs & Services" → "Credentials"
2. Click "Create Credentials" → "OAuth client ID"
3. Select "Desktop app" as application type
4. Name it (e.g., "Gmail MCP Desktop")
5. Click "Create"
6. Download or copy the Client ID and Client Secret

Installation

# Clone or navigate to the project
cd gmail-mcp

# Install dependencies
npm install

# Build the project
npm run build

Configuration

1. Copy the example environment file:

cp .env.example .env

2. Edit .env with your OAuth credentials:

CLIENT_ID=your-client-id.apps.googleusercontent.com
CLIENT_SECRET=your-client-secret

First Run (Authorization)

The first time you run the server, it will:

1. Open your browser for Google authorization
2. Ask you to sign in and grant permissions
3. Save the tokens locally in token.json

Subsequent runs will reuse the saved tokens automatically.

Usage with Claude Code

Add the MCP Server

claude mcp add gmail node ./dist/index.js

Or add to your Claude Code configuration manually:

{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": ["./dist/index.js"],
      "cwd": "/path/to/gmail-mcp"
    }
  }
}

Available Tools

search_emails

Search emails using Gmail query syntax.

Query examples:
- "from:user@example.com"
- "subject:meeting"
- "is:unread"
- "after:2024/01/01 before:2024/12/31"
- "has:attachment filename:pdf"
- "in:inbox -category:promotions"

list_unread

List unread emails (shortcut for is:unread search).

get_message

Get full content of a specific email by message ID.

get_thread

Get all messages in a conversation thread by thread ID.

draft_reply

Prepare a draft reply to a thread. Provides context for composing a response but does NOT send any email.

Development

# Run in development mode (with hot reload)
npm run dev

# Type check
npm run typecheck

# Build for production
npm run build

# Run production build
npm start

Security Notes

• OAuth tokens are stored locally in token.json
• Never commit .env or token.json to version control
• The server only requests read and compose permissions
• No emails are sent - draft_reply only prepares content
• Email content is not logged

Troubleshooting

"Missing CLIENT_ID or CLIENT_SECRET"

Ensure your .env file exists and contains valid credentials.

"Authorization timeout"

The OAuth flow has a 5-minute timeout. Restart the server and complete authorization promptly.

"Token refresh failed"

Delete token.json and re-authorize.

"Access blocked: This app's request is invalid"

Ensure your OAuth consent screen is properly configured and your email is added as a test user.