You can manage Gmail using an MCP server that orchestrates intelligent email handling, archiving, cleanup, search, and analytics through a modular set of tools. This guide shows you how to use the server with an MCP client, install it locally, and configure it for secure operation.

How to use

Connect your MCP client to the Gmail MCP Server using the supported standard input/output interface. You start the local server process and point the client at it, then authenticate with Gmail to enable reading, organizing, archiving, and cleaning up emails. You can run long-running tasks in the background, track progress, and apply policy-based cleanups with safety checks such as dry runs and confirmation prompts. Use the client to trigger actions like listing emails, archiving with export formats, restoring from archives, and scheduling automated cleanup rules. All operations respect safety limits and audit logging to protect your data.

How to install

# Prerequisites
- Node.js 18+ and npm
- Google Cloud Platform account with Gmail API enabled
- OAuth2 credentials (Client ID and Client Secret)

# Automated setup
git clone <repository-url>
cd gmail-mcp-server
npm run setup
npm install
npm run build

# First run
npm start

# Authenticate with Gmail from your MCP client after starting the server
{
  "tool": "authenticate"
}
}

If you prefer manual setup, ensure Gmail API credentials are prepared and environment variables are configured before building and starting the server.

Configuration

You can configure how the Gmail MCP Server connects and runs by using the MCP client setup and environment variables. The client setup examples show a local stdio connection using Node to run the built server, and a production-like configuration that passes environment values.

# MCP Client Setup example (stdio)
# In a client configuration file
{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": ["/path/to/gmail-mcp-server/build/index.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

# Explicit stdio connection command example
node /path/to/gmail-mcp-server/build/index.js

Environment variables shown in the example

GOOGLE_CLIENT_ID=your_client_id GOOGLE_CLIENT_SECRET=your_client_secret GOOGLE_REDIRECT_URI=http://localhost:3000/oauth2callback STORAGE_PATH=./data CACHE_TTL=3600 LOG_LEVEL=info

## Security & Safety

The server implements secure OAuth2 authentication, encrypted token storage, and audit logging. It provides multiple safety nets for bulk operations, including dry-run previews, confirmation prompts, and configurable maximum deletion limits. All communications with Gmail APIs use secure channels, and data is isolated per user with encrypted local metadata storage.

## Troubleshooting

If you encounter authentication issues, verify credentials.json placement, ensure the Gmail API is enabled in GCP, and confirm the OAuth2 redirect URI matches your configuration. For persistent token errors, clear cached tokens and re-authenticate. If operations are slow or fail, enable caching, review quotas, and consider using specific filters to reduce result sets.

## Example Workflows

Initial setup and basic email organization: authenticate, initialize statistics, categorize emails, and review results. Then perform a targeted search, archive selected emails, and monitor cleanup status.

## Notes on development and contributing

The server is modular and designed for extension. It uses a factory pattern for tools, a repository pattern for data access, and event-driven cleanup. Development workflows emphasize type safety, testing, and documentation, with clear steps to add new MCP tools, tests, and usage examples.

## Architecture overview

The Gmail MCP Server is built around a modular MCP Server Layer, a Business Logic Layer, a Data Layer with SQLite, and External Services like the Gmail API and cloud storage. This separation supports scalability and maintainability for large mailboxes.

## Available tools

### authenticate

Initiates the OAuth2 authentication flow with Gmail API and returns authentication status and user email.

### list\_emails

List emails with filtering options such as category, year, size, archived status, and labels.

### get\_email\_details

Retrieve complete email content and metadata for a given message ID.

### categorize\_emails

Analyze and categorize emails by importance using AI-driven analyses and optional force refresh.

### search\_emails

Advanced search with multiple criteria including query, category, year range, size range, sender, and attachments.

### save\_search

Save a search configuration for quick reuse.

### list\_saved\_searches

Return all saved searches with usage statistics.

### archive\_emails

Archive emails using various methods and formats, with options for dry runs and export formats.

### restore\_emails

Restore emails from previous archives and apply restore labels.

### create\_archive\_rule

Create automated archiving rules with scheduling.

### list\_archive\_rules

List all configured archive rules and their status.

### export\_emails

Export emails to external formats and optionally upload to cloud storage.

### delete\_emails

Safely delete emails with safety checks and optional dry-run previews.

### empty\_trash

Permanently delete all emails in Gmail trash with safety limits.

### trigger\_cleanup

Execute manual cleanup using specific policies with safety previews.

### get\_cleanup\_status

Monitor cleanup automation system status and active jobs.

### get\_system\_health

Retrieve system health, performance metrics, and storage usage.

### create\_cleanup\_policy

Create advanced cleanup policies with detailed criteria and safety configurations.

### update\_cleanup\_policy

Modify existing cleanup policy configurations.

### list\_cleanup\_policies

List all cleanup policies and their configurations.

### delete\_cleanup\_policy

Remove a cleanup policy permanently.

### create\_cleanup\_schedule

Schedule automatic cleanup policy execution.

### update\_cleanup\_automation\_config

Update global cleanup automation settings.

### get\_cleanup\_metrics

Retrieve cleanup system analytics and performance data.

### get\_cleanup\_recommendations

Get AI-powered cleanup policy recommendations.

### get\_email\_stats

Get comprehensive email usage statistics and analytics.

### list\_jobs

View all background jobs with filtering options.

### get\_job\_status

Get detailed status of a specific background job.

### cancel\_job

Cancel a running background job.