personal-gmail-mcp

A Model Context Protocol server that exposes a personal Gmail (consumer Google account) inbox and calendar to MCP clients like Claude Desktop. Talks to the Gmail and Google Calendar APIs over HTTPS, uses a local loopback OAuth flow, and stores tokens in the OS keyring.

Sibling to personal-outlook-mcp; same design (local stdio, keyring-backed tokens, you bring your own OAuth client), different provider. Tools are prefixed gmail_*.

Status: functional. Auth (loopback OAuth + keyring token cache), 12 mail tools, and 7 calendar tools are in place and verified against a live account. Published on npm as @jaingxyz/personal-gmail-mcp — install via npx (see below) or from source.

Why keyring + bring-your-own-client

Every Gmail MCP server we surveyed stores OAuth tokens as a plaintext JSON file in your home directory. This one stores them in the OS keyring (macOS Keychain / Windows Credential Manager / Linux Secret Service) via @napi-rs/keyring, and runs entirely locally — your mail never passes through anyone else's servers.

Related MCP server: MCP Google Workspace Server

Google setup (required, ~5 minutes, free)

You must create your own Google Cloud OAuth client.

1. Go to https://console.cloud.google.com → create a project.

2. APIs & Services → Library → enable both Gmail API and Google Calendar API.

3. APIs & Services → OAuth consent screen:

   • User type: External.

   • Add your own Google account as a test user.

   • Publish the app ("In production"). You can leave it unverified for personal use (you'll click through an "unverified app" warning at sign-in).

   • ⚠️ This step matters: an app left in "Testing" status issues refresh tokens that expire after 7 days — you'd have to re-auth every week. Publishing to production (even unverified) gives long-lived refresh tokens.

4. APIs & Services → Credentials → Create credentials → OAuth client ID → application type Desktop app. Copy the Client ID and Client secret.

5. cp .env.example .env and fill in GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET.

The required scopes are requested at sign-in; you consent at the browser prompt:

Changing the scope list invalidates the cached token — re-run npm run whoami to re-consent.

First run (loopback auth)

npm install
npm run build
npm run whoami

whoami opens your browser to Google's consent page (the URL is also printed to stderr if the browser doesn't open). After you approve, a throwaway 127.0.0.1 listener captures the redirect, exchanges the code, and stores the token set in the OS keyring under service personal-gmail-mcp. It then prints your Gmail profile as JSON. Subsequent runs refresh silently.

To sign out (forget the cached token):

node -e "import('./dist/auth.js').then(m => m.signOut())"

MCP client integration

Point your MCP client (Claude Desktop or similar) at the server. The simplest form uses npx to fetch the published package:

{
  "mcpServers": {
    "personal-gmail": {
      "command": "npx",
      "args": ["-y", "@jaingxyz/personal-gmail-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "<YOUR-CLIENT-ID>",
        "GOOGLE_CLIENT_SECRET": "<YOUR-CLIENT-SECRET>"
      }
    }
  }
}

If you cloned the repo instead, use the from-source form with an absolute path to the built dist/index.js:

{
  "command": "node",
  "args": ["/absolute/path/to/personal-gmail-mcp/dist/index.js"],
  "env": { "GOOGLE_CLIENT_ID": "...", "GOOGLE_CLIENT_SECRET": "..." }
}

If your node is managed by a version manager (nvm, mise, asdf), use the absolute path to the node binary (e.g. which node) — MCP clients launch with a minimal PATH and won't resolve a bare node.

Seed the keyring from a terminal once before launching the client — run npx -y @jaingxyz/personal-gmail-mcp whoami (or npm run whoami from a clone). The browser/consent step can't be surfaced from inside the app (stderr is swallowed), so the MCP server only does silent refresh and will report Re-authentication required if the cache is empty or stale.

Tools

All tools are prefixed gmail_* (mail) or gmail_calendar_* (calendar) so a multi-account setup can coexist.

Calendar event times use { dateTime, timeZone } where dateTime is local form (no offset) and timeZone is an IANA name. Output times default to America/Los_Angeles; override with PERSONAL_GMAIL_TZ.

How it differs from the Outlook server

License

AGPL-3.0-or-later. See LICENSE.

Acknowledgements

Built with assistance from Claude (Anthropic). Architecture and final review remain the human author's responsibility.