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

Tool	Description
list_emails	Recent mail (optional Gmail query)
search_emails	Search (from:, is:unread, etc.)
get_email	Full body by message ID
send_email	Send now
create_draft	Draft only
reply_to_email	Reply in-thread
archive_email	Remove from inbox
mark_read / mark_unread	Toggle unread
delete_email	Move to Trash
list_labels / create_label	Labels

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

Problem	Fix
mcp won’t install	Need Python 3.10+
Server not connected	Check paths; Cmd+Q Claude and reopen; see ~/Library/Logs/Claude/mcp-server-gmail.log
Access blocked	Add your Gmail as OAuth Test user
Re-login needed	Delete token.json and call a Gmail tool again

Never commit credentials.json or token.json.