Gmail Reader MCP Server

An MCP (Model Context Protocol) server that provides read-only access to your Gmail account. It exposes email subjects, senders, labels, categories, and full email content to LLM-powered tools like VS Code Copilot and Claude Desktop.

Features

• gmail_get_profile — Get your Gmail profile info (email, total messages)
• gmail_list_labels — List all labels with message/unread counts
• gmail_list_emails — List emails with optional Gmail search query and label filters (metadata only)
• gmail_search_emails — Search emails using Gmail query syntax (metadata only)
• gmail_get_email — Get the full content (text + HTML body) of a specific email by ID
• gmail_list_newsletters — List emails with the "Newsletter" label, with full content. Supports filtering by date, unread status, sender, subject, or any Gmail query.

---

Prerequisites

• Node.js 18+ installed
• A Google Cloud project with the Gmail API enabled
• OAuth 2.0 Desktop credentials (credentials.json)

---

Step 1: Google Cloud Console Setup

1.1 Create a project

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

1.2 Enable the Gmail API

1. In the sidebar, go to APIs & Services → Library
2. Search for Gmail API
3. Click Gmail API → Enable

1.3 Configure OAuth consent screen

1. Go to APIs & Services → OAuth consent screen
2. Choose User type:
   • Internal (if using Google Workspace — recommended, no verification needed)
   • External (for personal Gmail — will be in "Testing" mode, limited to test users you add)
3. Fill in:
   • App name: Gmail MCP Server
   • User support email: your email
   • Developer contact email: your email
4. On the Scopes page, click Add or Remove Scopes and add:

   https://www.googleapis.com/auth/gmail.readonly
   

5. Save and continue through the remaining steps

1.4 Create OAuth 2.0 credentials

1. Go to APIs & Services → Credentials
2. Click Create Credentials → OAuth client ID
3. Application type: Desktop app
4. Name: Gmail MCP Server (or anything)
5. Click Create
6. Click Download JSON — save this file as credentials.json in the project root

---

Step 2: Install & Build

# Install dependencies
npm install

# Build the TypeScript project
npm run build

---

Step 3: First Run (OAuth Authorization)

npm start

On the first run, the server will:

1. Open your browser to Google's OAuth consent screen
2. Ask you to sign in and grant read-only Gmail access
3. Redirect back to http://localhost:3000/oauth2callback
4. Save the token to ~/.gmail-mcp/tokens.json

Subsequent runs will reuse the saved token automatically.

---

Step 4: Connect to an MCP Client

VS Code (Copilot)

Add to your .vscode/mcp.json in the workspace (or user settings):

{
  "servers": {
    "gmail": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/gmail-mcp/dist/index.js"],
      "env": {
        "GMAIL_CREDENTIALS_PATH": "/ABSOLUTE/PATH/TO/credentials.json"
      }
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/gmail-mcp/dist/index.js"],
      "env": {
        "GMAIL_CREDENTIALS_PATH": "/ABSOLUTE/PATH/TO/credentials.json"
      }
    }
  }
}

MCP Inspector (Testing)

npx @modelcontextprotocol/inspector node dist/index.js

---

Environment Variables

Variable	Default	Description
GMAIL_CREDENTIALS_PATH	./credentials.json	Path to the OAuth credentials JSON file
GMAIL_TOKEN_PATH	~/.gmail-mcp/tokens.json	Where to store the OAuth refresh token
GMAIL_MAX_RESULTS	100	Default max results for list/search (max 100)

---

OAuth Scope

This server uses a single read-only scope:

https://www.googleapis.com/auth/gmail.readonly

This grants read access to:

• Email messages (metadata + full body content)
• Labels and categories
• User profile
• Threads

It does NOT allow sending, deleting, or modifying any emails.

---

License

MIT