home / mcp / gmail mcp server

Gmail MCP Server

A Gmail MCP server

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "theposch-gmail-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/gmail-mcp",
        "run",
        "gmail",
        "--creds-file-path",
        "/absolute/path/to/credentials.json",
        "--token-path",
        "/absolute/path/to/tokens.json"
      ]
    }
  }
}

This Gmail MCP Server lets you control Gmail through natural language via an MCP client. It enables you to send, read, label, archive, and manage drafts and filters, all from your AI assistant or internal workflows, using the Gmail API in a secure, scriptable way.

How to use

Connect an MCP client to the Gmail MCP Server to perform email actions through natural language prompts. You can use a local runner or an Inspector tool to test commands. Typical workflows include sending emails, reading messages, organizing with labels and folders, drafting emails for later, and applying filters or archiving groups of emails.

How to install

Prerequisites include Python 3.8 or newer, a Google Cloud project with the Gmail API enabled, and OAuth 2.0 credentials.

Install steps you can follow locally:

# Clone the project
git clone https://github.com/theposch/gmail-mcp.git
cd gmail-mcp

# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install the package in editable mode
pip install -e .

Additional configuration and setup

Prepare your Google Cloud credentials and tokens, then place them in a secure path you reference when starting the server.

# Example credentials directory
mkdir -p ~/.gmail-mcp
mv ~/Downloads/client_secret_*.json ~/.gmail-mcp/credentials.json

Running with an MCP client (stdio configuration)

Use the following command as the runtime server configuration in your MCP client. This runs the Gmail MCP Server from a local directory and points to your credentials and token files.

--directory /absolute/path/to/gmail-mcp
run gmail
--creds-file-path /absolute/path/to/credentials.json
--token-path /absolute/path/to/tokens.json

Testing with MCP Inspector

To test and debug the Gmail MCP Server, run the Inspector against the local Gmail MCP entry point.

npx @modelcontextprotocol/inspector uv run /path/to/gmail-mcp/src/gmail/server.py --creds-file-path /path/to/credentials.json --token-path /path/to/tokens.json

Additional usage notes

The server will request user confirmation before performing sensitive actions. Store credentials securely and review Google Cloud Console for unusual activity. Prefer environment variables for sensitive paths where possible.

Available tools

send_email

Send emails with customizable subject, content, and recipients.

read_email

Read and retrieve email content along with full metadata.

move_to_trash

Move emails to trash with confirmation.

mark_read_unread

Mark emails as read or unread.

open_email

Open emails directly in a browser.

draft_email

Create and manage draft emails for later review.

list_drafts

List all draft emails.

edit_draft

Edit existing drafts.

label_management

List, create, apply, rename, and delete labels.

label_by_search

Search emails by label.

folder_management

Create folders (labels), move emails between folders, list folders.

search_emails

Search emails using Gmail’s advanced query syntax.

manage_filters

Create, manage, and delete email filters.

archive_emails

Archive emails and batch archive based on search criteria.

restore_archived

Restore archived emails to inbox.