Codibly Gmail MCP Server

Enterprise MCP server by Codibly for comprehensive Gmail management - send emails, manage labels, search messages, and automate email workflows with AI assistance

Get Started Quick Setup →

🚀 Quick Setup with Authentication Helper

Connect Gmail to AI assistants with OAuth or Service Account authentication. Our built-in helper makes it easy to get your refresh token for personal Gmail or configure Google Workspace accounts.

Use Authentication Helper →

🔌 Test MCP Server Connection

Test your connection to the MCP wrapper server using your x-api-key. This validates that your MCP server credentials are configured correctly.

MCP Server API Key (x-api-key)

📧 Test Full Gmail Connection

Test both your MCP server connection AND your Gmail credentials. This ensures your complete setup is working correctly.

MCP Server API Key (x-api-key)

OAuth Client ID (x-client-id)

OAuth Client Secret (x-client-secret)

Refresh Token (x-gmail-refresh-token)

📡 API Endpoint & Required Headers

POST https://gmail.mcp.majewscy.tech

Required HTTP Headers:

Content-Type: application/json

x-api-key: Your MCP server API key

x-client-id: Your Google OAuth Client ID (for personal/workspace)

x-client-secret: Your Google OAuth Client Secret (for personal/workspace)

x-gmail-refresh-token: Your Gmail refresh token (get from /auth)

x-gmail-service-account: Service Account JSON (for Google Workspace)

x-gmail-delegated-email: Email to impersonate (for Service Accounts)

🛠️ Available Tools

gmail_send

Send emails with attachments and HTML content

gmail_read

Read email content and metadata

gmail_search

Search emails with advanced queries

gmail_list

List emails from inbox or labels

gmail_trash

Move emails to trash

gmail_untrash

Restore emails from trash

gmail_create_label

Create new Gmail labels

gmail_list_labels

List all available labels

gmail_update_label

Update existing labels

gmail_delete_label

Delete labels from account

gmail_add_label

Add labels to emails

gmail_remove_label

Remove labels from emails

Configuration

// Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
// Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": [
        "-y",
        "@gongrzhe/server-gmail-autoauth-mcp"
      ],
      "env": {
        "GMAIL_OAUTH_PATH": "/path/to/your/oauth.json",
        "GMAIL_CREDENTIALS_PATH": "/path/to/your/credentials.json"
      }
    }
  }
}

// HTTP Wrapper Configuration (for remote access)
{
  "gmail": {
    "type": "http",
    "url": "https://gmail.mcp.majewscy.tech",
    "headers": {
      "x-api-key": "YOUR_MCP_API_KEY",
      "x-client-id": "YOUR_GOOGLE_CLIENT_ID",
      "x-client-secret": "YOUR_GOOGLE_CLIENT_SECRET",
      "x-gmail-refresh-token": "YOUR_REFRESH_TOKEN"
    }
  }
}

// Claude Code: .mcp.json in your project root (for HTTP wrapper)
{
  "gmail": {
    "type": "http",
    "url": "https://gmail.mcp.majewscy.tech",
    "headers": {
      "x-api-key": "YOUR_MCP_API_KEY",
      "x-client-id": "YOUR_GOOGLE_CLIENT_ID",
      "x-client-secret": "YOUR_GOOGLE_CLIENT_SECRET",
      "x-gmail-refresh-token": "YOUR_REFRESH_TOKEN"
    }
  }
}

Features

Complete Gmail management for AI assistants with multiple authentication methods

📩

Email Management

Send, read, search, and organize emails with full Gmail API capabilities.

🏷️

Label Operations

Create, update, delete, and manage Gmail labels for email organization.

🔐

Multi-Auth Support

OAuth for personal accounts and Service Accounts for Google Workspace.

🏢

Workspace Ready

Domain-wide delegation support for Google Workspace administrators.

🔍

Advanced Search

Powerful Gmail search queries with filters and date ranges.

📎

Attachments

Handle email attachments for both sending and receiving messages.

📋 Recent Updates from GitHub

Latest Aug 26, 2025

Feature: Added Stage 2 validation for Gmail credentials
Feature: Implemented AWS MCP standards landing page design
Enhancement: Added proper error handling for invalid credentials

Recent Aug 25, 2025

Feature: Multi-authentication support (OAuth + Service Account)
Feature: Built-in authentication helper at /auth
Enhancement: Support for Google Workspace domain delegation

View on GitHub →

🔐 Update Server