MCP Gmail Server

A Model Context Protocol (MCP) server that provides Gmail access for LLMs, powered by the MCP Python SDK.

Features

- Expose Gmail messages as MCP resources
- Provide tools for composing, sending, and managing emails
- OAuth 2.0 authentication with Google's Gmail API

Prerequisites

- Python 3.10+
- Gmail account with API access
- uv for Python package management (recommended)

Setup

1. Install dependencies

Install project dependencies (uv automatically creates and manages a virtual environment)

uv sync

2. Configure Gmail OAuth credentials

There's unfortunately a lot of steps required to use the Gmail API. I've attempted to capture all of the required steps (as of March 28, 2025) but things may change.

Google Cloud Setup

1. Create a Google Cloud Project
- Go to Google Cloud Console
- Click on the project dropdown at the top of the page
- Click "New Project"
- Enter a project name (e.g., "MCP Gmail Integration")
- Click "Create"
- Wait for the project to be created and select it from the dropdown

2. Enable the Gmail API
- In your Google Cloud project, go to the navigation menu (≡)
- Select "APIs & Services" > "Library"
- Search for "Gmail API"
- Click on the Gmail API card
- Click "Enable"

3. Configure OAuth Consent Screen
- Go to "APIs & Services" > "OAuth consent screen"
- You will likely see something like "Google Auth Platform not configured yet"
- Click on "Get started"
- Fill in the required application information:
- App name: "MCP Gmail Integration"
- User support email: Your email address
- Fill in the required audience information:
- Choose "External" user type (unless you have a Google Workspace organization)
- Fill in the required contact information:
- Your email address
- Click "Save and Continue"
- Click "Create"

4. Create OAuth Credentials
- Go to "APIs & Services" > "Credentials"
- Click "Create Credentials" > "OAuth client ID"
- Choose "Desktop app" as the application type
- Enter a name (e.g., "MCP Gmail Desktop Client")
- Click "Create"
- Click "Download JSON" for the credentials you just created
- Save the file as credentials.json in your project root directory

5. Add scopes
- Go to "APIs & Services" > "OAuth consent screen"
- Go to the "Data Access" tab
- Click "Add or remove scopes"
- Search for the Gmail API
- Select the scope for .../auth/gmail.modify which grants permission to "Read, compose, and send emails from your Gmail account"
- Click update
- Click save

Verify that you've set up your OAuth configuration correctly by running a simple test script.

uv run python scripts/test_gmail_setup.py

You should be able to see usage metrics at https://console.cloud.google.com/apis/api/gmail.googleapis.com/metrics

3. Run the server

Development mode:

uv run mcp dev mcp_gmail/server.py

This will spin up an MCP Inspector application that you can use to interact with the MCP server.

Or install for use with Claude Desktop:

uv run mcp install \

    --with-editable .

    --name gmail \

    --env-var MCP_GMAIL_CREDENTIALS_PATH=$(pwd)/credentials.json \

    --env-var MCP_GMAIL_TOKEN_PATH=$(pwd)/token.json \

    mcp_gmail/server.py

> [!NOTE]
> If you encounter an error like Error: spawn uv ENOENT when spinning up Claude Desktop and initializing the MCP server, you may need to update your claude_desktop_config.json to provide the absolute path to uv. Go to Claude Desktop -> Settings -> Developer -> Edit Config.
>
>

> {

>   "mcpServers": {

>     "gmail": {

>       "command": "~/.local/bin/uv",

>     }

>   }

> }

> 

Development

Linting and Testing

Run linting and formatting:
```bash