📧 Gmail MCP Server

An MCP server to integrate Gmail with Claude, Cursor, and other MCP clients. Allows AI agents to read, search, draft, and send emails securely.

---

🚀 Quickstart

Option 1: Remote Usage - Recommended ⭐

This method requires no local python installation.

Add this to your mcp_config.json:

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

How to use:

1. Ask a question (e.g., "Check my email").
2. You will get a URL. Click to authorize Google.
3. Copy the code and paste it into the chat.
4. You are logged in!

---

Option 2: Local Usage (For Developers)

If you prefer to run the server code locally on your machine.

1. Install Dependencies

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

2. Get Google Credentials

1. Go to Google Cloud Console.
2. Create Project → Enable Gmail API.
3. Credentials → Create OAuth Client ID → Desktop App.
4. Download JSON → rename to credentials.json → place in this folder.

3. Authenticate (One-time)

python authenticate.py

This opens your browser for Google login and creates token.json automatically.

4. Configure Editor

Add this to your mcp_config.json:

{
  "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.

Example Config:

<img width="632" height="202" alt="image" src="https://github.com/user-attachments/assets/f051873a-92e7-41be-a8d4-87730280a676" />

---

🛠️ Features

Tools

Tool	Description
list_emails	List/search emails (returns id, snippet, subject, from, date)
read_email	Read full email content by ID
create_draft	Create a draft email (requires send_draft to actually send)
send_draft	Send a drafted email

Prompts

Prompt	Description
summarize_unread	Summarize unread emails with priority
draft_reply	Draft reply to an email
compose_email	Compose new email
search_emails	Natural language email search
daily_digest	Daily email digest by category

---

📁 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

---

🔒 Security

• credentials.json: Identifies the application. Low risk if shared, but keep private.
• token.json: CRITICAL. Contains acts-as-you keys. NEVER SHARE.
• .gitignore: Ensure both JSON files are ignored (default in this repo).

Note: send_draft sends real emails. Use responsibly.