Gmail MCP Server

What is this?

The Gmail MCP Server is a powerful extension that wraps the Gmail REST API in an AI-friendly Model Context Protocol (MCP) interface, making it simple to read, search, organize, and send emails in your applications. It handles secure OAuth2 flows, token storage, and batch and MIME operations out of the box, so you can focus on building intelligent workflows instead of plumbing. Packaged as @modelcontextprotocol/server-gmail, it plugs seamlessly into any MCP-compliant agent or client, providing a consistent API surface and built-in error handling.

You can standardize Gmail interactions under one protocol, automating tasks like inbox triage, smart reply generation, and context propagation across conversations. With comprehensive support for messages, threads, labels, drafts, attachments, and batch endpoints, the server accelerates development, optimizes API usage, and ensures consistent performance even at scale.

Quick Start

Install the server using npm:

npm install @modelcontextprotocol/server-gmail

Then add it to your MCP client configuration:

{
  "mcpServers": {
    "server-gmail": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-gmail"],
      "env": {
        "API_KEY": "your-api-key-here"
      }
    }
  }
}

Key Features

Feature 1: Secure OAuth2-based delegated access that never exposes raw user credentials, with support for PKCE, service accounts, and automatic token refresh.

Feature 2: Full Gmail API coverage for messages, threads, labels, drafts, and attachments, plus built-in MIME parsing and composition for robust email workflows.

Feature 3: Batch operations and high-throughput tooling to minimize API calls, optimize quota usage, and handle large volumes of messages efficiently.

Example Usage

You can use the Gmail MCP Server to power an AI agent that lists a user’s recent emails, applies labels based on keywords, or sends context-aware replies automatically.

// Example code
const result = await client.callTool({
  name: "gmail.listMessages",
  arguments: {
    userId: "alice@example.com",
    maxResults: 10
  }
});

This call retrieves up to 10 recent messages for the specified user, returning an array of message IDs and metadata for downstream processing.

Configuration

The server accepts the following environment variables:

API_KEY – Your Google API key or OAuth2 client credentials to authenticate Gmail requests.

OAUTH_CREDENTIALS_PATH (optional) – File path to a JSON file containing your OAuth2 client ID and secret (defaults to credentials.json).

Available Tools/Resources

gmail.listMessages: Retrieve a list of email messages for a given user.

gmail.sendMessage: Send a raw MIME-formatted email message through the Gmail API.

Who Should Use This?

This server is perfect for:

Use case 1: AI developers building chatbots or assistants that need to read, analyze, or send emails dynamically.

Use case 2: Teams automating email workflows like triage, reminders, or bulk messaging within existing MCP frameworks.

Use case 3: Workflow integration platforms seeking a standardized, secure, and scalable way to interact with Gmail.

Conclusion

The Gmail MCP Server streamlines secure, AI-powered Gmail interactions under a single MCP-compliant API, so you can spend less time on integration and more time on intelligent features. Give it a try today and see how quickly you can add email automation and context-aware messaging to your projects!

Check out the GitHub repository for more information and to contribute.