Gmail MCP Server

This project provides a set of Gmail tools built with the MCP (Model Context Protocol) framework, allowing AI clients like Claude Desktop to send emails, create drafts, and read Gmail labels through Google's Gmail API. Tools are registered with FastMCP and can be tested via the MCP Inspector or connected directly to Claude Desktop.

Features

• 📤 Send emails through Gmail
• 📝 Create email drafts
• 🏷️ Read Gmail labels

Prerequisites

• Python 3.10+
• uv for dependency management
• MCP CLI (mcp[cli])
• Gmail API credentials (client_secret.json)

Enable Gmail API and Download Credentials

1. Go to the Google Cloud Console
2. Create a new project (or use an existing one)
3. Enable the Gmail API
4. Configure the OAuth consent screen and add yourself as a test user
5. Create OAuth 2.0 Client ID credentials with application type Desktop app
6. Download the client_secret.json file and place it in the project root

Setup

1. Clone the repository

git clone https://github.com/AsifMarwat/Gmail-mcp.git
cd Gmail-mcp

2. Install dependencies

uv sync

Note: If you're not using uv, you can also run:

pip install -r requirements.txt

3. Add your credentials

Place your downloaded client_secret.json in the project root. On first run, the app will open a browser window for you to sign in and authorize access — this generates a token.json file that stores your session so you don't need to log in again.

Running the Project

Development (MCP Inspector)

Use this to test your tools directly in the MCP Inspector:

uv run mcp dev main.py

Connect to Claude Desktop

Add the server to your claude_desktop_config.json:

{
  "mcpServers": {
    "gmail-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/Gmail-mcp",
        "run",
        "python",
        "main.py"
      ]
    }
  }
}

Restart Claude Desktop after saving. The Gmail tools will then be available directly in your conversations.

Available Tools

Tool	Description
create_draft	Creates a draft email in Gmail
send_mail	Sends an email directly from Gmail
read_labels	Reads all Gmail label information

Project Structure

.
├── main.py                # Script defining Gmail tools
├── client_secret.json     # OAuth credentials (keep private, not committed)
├── token.json             # Generated after first login (keep private, not committed)
├── pyproject.toml         # Project dependencies
├── uv.lock                # Locked dependency versions
└── README.md              # Project documentation

Notes

• The script generates and uses token.json for storing OAuth tokens after your first authorization.
• Do not commit client_secret.json or token.json to version control. Both are excluded via .gitignore.
• This project was built as a learning exercise to understand how MCP servers integrate with the Gmail API and AI clients like Claude Desktop.