Gmail MCP Server

Local MCP server that lets Claude Desktop read and manage your Gmail (list, search, send, draft, reply, archive, labels, trash).

Claude asks → this server calls the Gmail API → actions run on your account.

Structure

gmail-mcp-server/
├── server.py         # MCP tools + dispatch
├── gmail_auth.py     # OAuth + token cache
├── gmail_tools.py    # Gmail API wrappers
├── requirements.txt
├── credentials.json  # from Google (do not commit)
└── token.json        # created after first login (do not commit)

Setup

1. Install (Python 3.10+)

cd gmail-mcp-server
/opt/homebrew/bin/python3.12 -m venv .venv   # or any python3.10+
source .venv/bin/activate
pip install -r requirements.txt

2. Google Cloud credentials

1. Google Cloud Console → create/select a project.

2. Enable Gmail API.

3. OAuth consent screen → External → fill app info → add yourself as a Test user (keep status Testing).

4. Credentials → Create → OAuth client ID → type Desktop app → download JSON.

5. Save it as credentials.json in this folder (must have an "installed" key, not "web").

3. Claude Desktop config

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "gmail": {
      "command": "/Users/mdparwezansari/Desktop/gmail-mcp-server/.venv/bin/python",
      "args": ["/Users/mdparwezansari/Desktop/gmail-mcp-server/server.py"]
    }
  }
}

Use absolute paths. Quit Claude fully (Cmd+Q) and reopen.

Claude starts the server automatically — you don’t need to run python server.py yourself.

4. First OAuth

In Claude, ask e.g. “List my recent emails.” Approve Google in the browser. That creates token.json for later runs.

Tools

Scope: gmail.modify (change in gmail_auth.py if you want less access).

Optional env

• GMAIL_CREDENTIALS_PATH — default ./credentials.json

• GMAIL_TOKEN_PATH — default ./token.json

Troubleshooting

Never commit credentials.json or token.json.