📬 Gmail MCP Server

A custom, open-source Model Context Protocol (MCP) server that connects AI assistants (Google Antigravity IDE, Claude Desktop, Cursor) directly to your Gmail account using the official Google Workspace APIs.

🌟 Highlights

• Complete Email Actions: Search, read, compose drafts, send emails, modify labels, and trash messages.

• Smart Content Extraction: Automatically handles multipart MIME messages, decodes Base64 data, extracts attachment metadata, and formats HTML into clean text.

• Local & Secure: Runs completely locally over stdio transport. Your credentials and tokens never leave your machine.

• Automatic Token Management: Performs interactive browser OAuth on the first run and silently refreshes expired tokens thereafter.

• Multi-Client Support: Works with Antigravity IDE, Claude Desktop, Cursor, and any MCP-compliant client.

Related MCP server: Gmail MCP Server

🛠️ Available MCP Tools

📚 Documentation & Guides

• Complete Run & Setup Guide (RUN_GUIDE.md) — Step-by-step instructions for running OAuth login and testing.

🚀 Quickstart

1. Clone & Set Up the Virtual Environment

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

# Create virtual environment and install dependencies
python3 -m venv .venv
source .venv/bin/activate
pip install -r <(python3 -c "import tomllib; [print(d) for d in tomllib.load(open('pyproject.toml','rb'))['project']['dependencies']]")
# Or using uv:
# uv sync

2. Add Google OAuth Credentials

1. Go to the Google Cloud Console.

2. Create a project and enable the Gmail API.

3. Configure the OAuth Consent Screen (add your Gmail address under Test users).

4. Go to Credentials ➔ Create Credentials ➔ OAuth client ID ➔ Application type: Desktop app.

5. Download the JSON file, copy it into this repository folder, and name it credentials.json (or keep its client_secret_*.json name).

⚠️ Security Warning: Never commit credentials.json, client_secret_*.json, or token.json to GitHub. They are already listed in .gitignore.

3. One-Time Authentication

Run the authentication helper in your terminal:

.venv/bin/python auth.py

A browser window will open asking you to sign in with your Google account. Once granted, it saves your credentials locally to token.json.

4. Test Email Operations (Optional)

Verify that your connection and tools work:

.venv/bin/python example_usage.py

🤖 AI Assistant Configuration

Google Antigravity IDE

Add the server to ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "gmail": {
      "command": "/absolute/path/to/Gmail-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/Gmail-mcp/server.py"],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "gmail": {
      "command": "/absolute/path/to/Gmail-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/Gmail-mcp/server.py"]
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json or your project .cursor/mcp.json:

{
  "mcpServers": {
    "gmail": {
      "command": "/absolute/path/to/Gmail-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/Gmail-mcp/server.py"]
    }
  }
}

📁 Repository Structure

├── auth.py                  # OAuth 2.0 flow & token management
├── tools/                   # Pure Python Gmail API tool operations
│   ├── reader.py            # Search & read email operations
│   ├── sender.py            # Send & draft email operations
│   ├── manager.py           # Trash & label management
│   └── __init__.py          # Exported tools package
├── server.py                # MCP Server entrypoint exposing tools via stdio
├── example_usage.py         # Standalone script demonstrating tool usage
├── credentials.template.json# Sample template for credentials
├── pyproject.toml           # Project dependencies & packaging config
├── RUN_GUIDE.md             # Detailed run & troubleshooting guide
├── MCP_GUIDE.md             # Beginner's guide to MCP & building new servers
└── README.md                # Project documentation

🛡️ License

This project is open-source under the MIT License.