Gmail MCP Server

How to use

You can use this Gmail MCP server in two ways: remote usage with an online MCP endpoint, or run a local instance for testing. The remote method requires no local Python installation and uses an HTTP-based MCP URL. The local method runs the server on your machine via Python and integrates with your Google credentials.

To use the remote server, configure your MCP client to connect to the remote endpoint and authorize Google when prompted by the client. You will receive a URL to authorize access; complete the flow and paste the code back into the chat to finish authentication.

To use the local server, set up your Python environment, obtain Google credentials, authenticate to create a token, and point your client at the local script. The remote and local methods coexist in your MCP configuration so you can switch between them as needed.

Example remote configuration you place in your MCP config file to use the online Gmail MCP server (no local Python required):

{
  "mcpServers": {
    "gmail_remote": {
      "url": "https://gmail-mcp-server-fr3d.onrender.com/mcp",
      "transport": "sse"
    }
  }
}

How to install

Prerequisites: you need Python 3 and pip installed on your machine. You also need a Google Cloud project with Gmail API enabled and OAuth credentials.

Step 1 — Install dependencies locally

cd Gmail-mcp-server
pip install -r requirements.txt

Step 2 — Get Google Credentials

1) Go to Google Cloud Console. 2) Create a project and enable Gmail API. 3) Credentials → Create OAuth Client ID → Desktop App. 4) Download the JSON, rename it to credentials.json, and place it in this folder.

Step 3 — Authenticate (one-time)

python authenticate.py

Step 4 — Configure the local editor integration in your MCP config

{
  "mcpServers": {
    "gmail": {
      "command": "python",
      "args": ["<ABSOLUTE_PATH_TO_REPO>/server.py"]
    }
  }
}
```
*Note: Replace <ABSOLUTE_PATH_TO_REPO> with the actual full path to this directory.*

Security

Keep credentials.json private. The token.json file contains sensitive access tokens and must never be shared. Ensure both files are ignored by your version control system.

Note that the send_draft tool actually sends real emails, so use it responsibly and verify privacy and authorization before sending.

File Structure

gmail-mcp-server/
├── server.py          # Main MCP server (FastMCP)
├── gmail_client.py    # Gmail API wrapper library
├── auth.py            # OAuth2 & Auth logic
├── credentials.json   # Google App Credentials (YOU PROVIDE)
├── token.json         # User Access Token (GENERATED)
└── requirements.txt   # Python dependencies

Notes and tips

The following tools are available to interact with Gmail through this MCP server: list_emails, read_email, create_draft, and send_draft. Prompts include summarize_unread, draft_reply, compose_email, search_emails, and daily_digest. These enable you to list, read, draft, search, and summarize emails, as well as compose new messages and reply to existing ones.

list_emails

List/search emails with id, snippet, subject, from, and date.

read_email

Read the full content of an email by its ID.

create_draft

Create a draft email; use send_draft to actually send it.

send_draft

Send a drafted email to the recipient.

summarize_unread

Summarize unread emails with priority.

draft_reply

Draft a reply to an existing email.

compose_email

Compose a new email from scratch.

search_emails

Perform natural language searches across emails.

daily_digest

Provide a daily digest of emails by category.