Gmail IMAP MCP Server

Name: Gmail IMAP MCP Server
Author: tonykipkemboi

@tonykipkemboi

Repository

About Gmail IMAP MCP Server

Gmail IMAP MCP server for integrating Gmail with Claude and other AI assistants

#gmail #imap #mcp #ai-assistant #email-integration

Basic information

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "gmail-imap-mcp": {
      "command": "python",
      "args": [
        "-m",
        "gmail_imap_mcp.server"
      ]
    }
  }
}

Tools

No tools detected

We auto-extract tools from the README. The maintainer can list them under a ## Tools heading to populate this section.

Overview

What is Gmail IMAP MCP Server?

A Model Context Protocol (MCP) server for Gmail integration using IMAP. It enables AI assistants to read, search, and manage Gmail accounts through OAuth2 authentication and a set of IMAP-based tools.

How to use Gmail IMAP MCP Server?

Install from source with Python 3.12+, enable the Gmail API in a Google Cloud project, create OAuth2 credentials, and run the command gmail-imap-mcp. Use the authenticate-gmail tool to authenticate an account, then invoke tools like search-emails, send-email, or create-label.

Key features of Gmail IMAP MCP Server

OAuth2 authentication with Gmail
Read, search, and send emails with attachments
Manage labels (create, delete, list)
Move emails between labels
Download attachments from emails
Mark emails as read/unread
Support for multiple Gmail accounts simultaneously

Use cases of Gmail IMAP MCP Server

An AI assistant reads and summarizes recent inbox emails for a user.
A user instructs an AI to search for emails from a specific sender and reply.
An AI helps organize emails by creating labels and moving messages between them.
A developer integrates Gmail management into a custom MCP-enabled AI workflow.

FAQ from Gmail IMAP MCP Server

How do I authenticate a Gmail account?

Use the authenticate-gmail tool with your email address. An OAuth2 flow will open in your browser; after granting permission, the server stores the token for future sessions.

What are the prerequisites?

Python 3.12 or higher, a Google Cloud Project with the Gmail API enabled, and OAuth 2.0 Client ID credentials (download as client_secret.json).

How do I start the server and connect it to Claude Desktop?

Run python -m gmail_imap_mcp.server to start the server. Then in Claude Desktop, navigate to Settings and configure the MCP server endpoint.

Where are credentials stored?

OAuth credentials and tokens are stored in ~/.gmail_imap_mcp_credentials/ — separate token files per account (format token_{email}.json). This location is user‑specific and persists across sessions.

What is the email ID format?

Email IDs follow the pattern email://message/{account}_{mailbox}_{id}, where account is the Gmail address, mailbox is the label, and id is the IMAP unique ID.