gmail-mcp

A read-only, multi-account Gmail MCP server for Claude Code. Lets Claude search threads, read messages, and list labels across one or more Gmail accounts you've authorized, over stdio.

Tools

All access is read-only (gmail.readonly scope) — this server cannot send, delete, or modify anything in Gmail.

Related MCP server: mcp-gmail

Setup

1. Install dependencies

npm install

2. Get OAuth credentials

1. Create (or reuse) a project in the Google Cloud Console.

2. Enable the Gmail API.

3. Create an OAuth client ID of type Desktop app.

4. Download the credentials and save them as credentials.json in the project root.

credentials.json and everything under tokens/ are gitignored — never commit them.

3. Authorize one or more Gmail accounts

npm run build
npm run auth -- youraccount@gmail.com

This opens a Google consent screen in your browser and, on approval, saves the resulting token to tokens/youraccount@gmail.com.json. Repeat for each account you want Claude to have access to.

4. Register the server with Claude Code

Point Claude Code at the built server, e.g. in your MCP config:

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

Development

npm run build   # compile TypeScript to dist/
npm start        # run the compiled server

Project structure

src/
  auth.ts    # one-off OAuth flow: authorizes an account and saves its token
  index.ts   # MCP server: exposes search_threads, get_message, list_labels, list_accounts

Tokens are stored per account in tokens/<email>.json and are loaded on demand from TOKENS_DIR at request time, so accounts can be added or removed without restarting the server.