mcp-gmail

An MCP (Model Context Protocol) server that connects Claude with Gmail through the Google Gmail API.

Quick Start

1. Install dependencies: npm install.

2. Set up Google Cloud credentials — see Google Cloud Console Setup.

3. Configure environment — copy .env.example to .env.development and add your Google OAuth credentials.

4. Build: npm run build.

5. Configure Claude Desktop with dist/mcp-server/index.js and your GMAIL_CLIENT_ID/GMAIL_CLIENT_SECRET (see Configuration).

6. Start the auth server: npm run dev:auth (separate process; handles OAuth on localhost:3334).

7. Authenticate — use the authenticate tool in Claude, follow the URL, sign in. Tokens are saved to ~/.mcp-gmail-tokens.json.

Installation

Prerequisites

• Node.js 22.0.0 or higher

• npm

• A Google account for Cloud Console access

Install Dependencies

npm install

Google Cloud Console Setup

1. Create a project

1. Open the Google Cloud Console.

2. Click the project dropdown at the top → New Project.

3. Name it (e.g. mcp-gmail) → Create.

4. Make sure the new project is selected in the dropdown.

2. Enable the Gmail API

1. Go to APIs & Services → Library.

2. Search for Gmail API → click it → Enable.

3. Configure the OAuth consent screen

For a brand-new project, Google now gates this behind a one-time "Google Auth Platform" wizard. If you see "Google Auth Platform not configured yet" with a Get Started button, follow 3a. Otherwise jump to 3b.

3a. First-time setup (Get Started wizard)

1. Go to APIs & Services → OAuth consent screen → click Get Started.

2. App Information: App name (e.g. MCP Gmail), user support email (your Gmail address) → Next.

3. Audience: select External → Next.

4. Contact Information: developer contact email (your Gmail address) → Next.

5. Finish: agree to the Google API Services User Data Policy → Continue → Create.

3b. Publish the app

1. Go to APIs & Services → OAuth consent screen → Audience (or the "Audience" tab on the new Google Auth Platform page).

2. Under Publishing status, click Publish App → Confirm.

   • This avoids the 7-day refresh-token expiry that applies to apps left in testing mode.

   • Your app stays "unverified" — that's fine for personal use; you'll see a one-time "advanced → continue" warning during sign-in.

3c. Configure data access (scopes)

This step is mandatory and easy to miss. If a scope isn't pre-declared here, Google silently drops it from the consent screen and the resulting tokens only carry the scopes Google adds by default (openid, userinfo.email). Any Gmail API call would then return 403 — the auth flow appears to succeed but the token can't read mail.

1. Go to APIs & Services → OAuth consent screen → Data Access (or the "Data Access" tab on the new Google Auth Platform page) → Add or remove scopes.

2. In the filter, search for Gmail API and tick the scopes you want. The default this server requests is:

   • https://www.googleapis.com/auth/gmail.modify — read, send, delete, and manage messages and labels (restricted scope).

   If you override GMAIL_SCOPES, add every scope you intend to request here as well.

3. Click Update → Save.

4. gmail.modify is a Google "restricted" scope. For personal use on an unverified app this is fine (you'll see an "advanced → continue" warning during sign-in and a cap of ~100 test users). Google only requires CASA verification if you ever publish the app to a wider audience.

After changing scopes here, delete ~/.mcp-gmail-tokens.json and re-run the authenticate tool so the consent screen prompts again with the new scope set.

4. Create OAuth credentials

1. Go to APIs & Services → Credentials.

2. Click Create Credentials → OAuth 2.0 Client ID.

3. Application type: Web application.

4. Name: anything (e.g. mcp-gmail).

5. Under Authorized redirect URIs, add:

   • http://localhost:3334/auth/callback (must match GMAIL_REDIRECT_URI — see Configuration)

6. Click Create.

7. Copy the Client ID and Client Secret from the confirmation dialog — you'll put them in .env.development as GMAIL_CLIENT_ID and GMAIL_CLIENT_SECRET. There's no credentials.json to download; the secret lives in env vars, never on disk in the repo.

Configuration

Environment Variables

Notes:

• If you change GMAIL_AUTH_PORT, update GMAIL_REDIRECT_URI (and the registered redirect URI in Google Cloud Console) to match.

• Use GMAIL_CLIENT_ID and GMAIL_CLIENT_SECRET consistently across .env.development and the Claude Desktop config.

Claude Desktop Configuration

Run npm run build first so dist/mcp-server/index.js exists, then add to your Claude Desktop config:

{
  "mcpServers": {
    "mcp-gmail": {
      "command": "node",
      "args": ["/path/to/mcp-gmail/dist/mcp-server/index.js"],
      "env": {
        "GMAIL_CLIENT_ID": "your-client-id",
        "GMAIL_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

A starter is in claude-config-sample.json.

Running From Source (Dev)

cp .env.example .env.development
# edit .env.development with your Google OAuth credentials, then:
npm run dev:mcp        # MCP server
npm run dev:auth       # OAuth server on :3334

The dev:mcp, dev:auth and inspect npm scripts run with NODE_ENV=development, and src/config.ts calls process.loadEnvFile('./.env.${NODE_ENV}') at startup — so it picks up .env.development from the CWD automatically. Claude Desktop does not set NODE_ENV, so the file is ignored in production; env vars must come from the Claude Desktop config env block.

Authentication

The OAuth flow runs out-of-band via the standalone auth server:

1. Start the auth server: npm run dev:auth (listens on http://localhost:3334).

2. In Claude, call the authenticate tool — it returns a sign-in URL.

3. Open the URL, sign in with the Google account you want to access, and grant the requested scopes.

4. Tokens (including a refresh token) are saved to ~/.mcp-gmail-tokens.json.

5. The MCP server reads that file and refreshes tokens transparently when they expire.

To force re-authentication (or if the refresh token is revoked), delete ~/.mcp-gmail-tokens.json and re-run the authenticate tool.

Scope troubleshooting. If Gmail API calls return 403 after a successful sign-in, inspect the scope field in ~/.mcp-gmail-tokens.json — Google only grants scopes that are pre-declared on the OAuth consent screen → Data Access tab (see step 3c). If gmail.modify is missing from scope, add it to Data Access, delete the token file, and re-authenticate.

Security Model

• Secrets (GMAIL_CLIENT_SECRET) come from env vars only; never committed. .env* files are gitignored except .env*.example templates.

• OAuth tokens live in ~/.mcp-gmail-tokens.json (mode 0600 when written). The MCP server reads, refreshes, and rewrites this file but never logs token values.

• The auth server binds to localhost:3334 only and accepts a single OAuth callback at a time; pending CSRF state entries expire after 10 minutes.

• If the token file is lost, revoked, or you want to switch Google accounts, delete ~/.mcp-gmail-tokens.json and re-authenticate.

Development

npm run dev:mcp        # tsx watch mode, MCP server (NODE_ENV=development)
npm run dev:auth       # tsx watch mode, OAuth server (NODE_ENV=development)
npm run start:mcp      # build then run MCP server from dist/
npm run start:auth     # build then run auth server from dist/
npm run inspect        # MCP Inspector against TS source (NODE_ENV=development)
npm test               # vitest
npm run typecheck      # tsc --noEmit
npm run lint:check     # Biome lint + format check
npm run lint:fix       # Biome auto-fix (uses --unsafe)
npm run lint:md        # prettier + markdownlint for *.md