Gmail

HTTPv1.0.0Credential RequiredJan 22, 2026

Documentation

Guide

Manage Gmail inbox, send emails, and organize messages via API.

A Model Context Protocol (MCP) server that exposes Gmail's API for comprehensive email management, including sending, receiving, searching, and organizing messages.

Overview

The Gmail MCP Server provides stateless, multi-user access to Gmail's core operations:

Message Management — Send, receive, retrieve, delete, and organize email messages
Email Organization — Create labels, manage message labels, and organize inbox efficiently
Search & Filtering — Advanced message search using Gmail search syntax
Draft & Thread Management — Create drafts, manage email threads, and track read/unread status

Perfect for:

Automated email workflow automation and processing
Building AI-powered email management systems
Integrating email capabilities into multi-agent applications

Tools

Inputs:

oauth_token (object, required) — Valid Google OAuth token object with Gmail scopes

Output:

{
  "result": {
    "emailAddress": "user@gmail.com",
    "messagesTotal": 1234,
    "threadsTotal": 456,
    "historyId": "123456789"
  }
}

Usage Example:

POST /mcp/cl-gmail/get_profile
 
{
  "oauth_token": {
    "token": "ya29.a0AfH6SMxxxxxxxxxxxxxx",
    "refresh_token": "1//0xxxxx",
    "token_uri": "https://oauth2.googleapis.com/token",
    "client_id": "xxx.apps.googleusercontent.com",
    "client_secret": "xxxxx",
    "scopes": ["https://www.googleapis.com/auth/gmail.readonly"]
  }
}

Inputs:

oauth_token (object, required) — Valid Google OAuth token object
message_id (string, required) — The message ID to retrieve
format (string, optional) — Response format: "full", "minimal", or "raw" (default: "full")

Output:

{
  "result": {
    "id": "msg-123456",
    "threadId": "thread-789",
    "labelIds": ["INBOX", "UNREAD"],
    "snippet":

Inputs:

oauth_token (object, required) — Valid Google OAuth token object
to (string, required) — Recipient email address
subject (string, required) — Email subject line
body (string, required) — Email body content
cc (string, optional) — CC recipients (comma-separated, default: "")
bcc (string, optional) — BCC recipients (comma-separated, default: "")

Output:

{
  "result": {
    "message": "Email sent successfully",
    "id"

Inputs:

oauth_token (object, required) — Valid Google OAuth token object
to (string, required) — Recipient email address
subject (string, required) — Email subject line
body (string, required) — Email body content
attachment_path (string, required) — Local file path to attach
cc (string, optional) — CC recipients (comma-separated, default: "")

Output:

{
  "result": {
    "message": "Email with attachment sent successfully",

Inputs:

oauth_token (object, required) — Valid Google OAuth token object
message_id (string, required) — The message ID to reply to
body (string, required) — Reply body content

Output:

{
  "result": {
    "message": "Reply sent successfully",
    "id": "msg-555444",
    "threadId": "thread-456"
  }
}

Inputs:

oauth_token (object, required) — Valid Google OAuth token object
message_id (string, required) — The message ID to delete

Output:

{
  "result": {
    "message": "Message deleted permanently",
    "id": "msg-123456"
  }
}

Usage Example:

POST

Inputs:

oauth_token (object, required) — Valid Google OAuth token object
message_id (string, required) — The message ID to trash

Output:

{
  "result": {
    "message": "Message moved to trash",
    "id": "msg-123456"
  }
}

Usage Example:

POST /mcp/cl-gmail/trash_message

Inputs:

oauth_token (object, required) — Valid Google OAuth token object
message_id (string, required) — The message ID to restore

Output:

{
  "result": {
    "message": "Message restored from trash",
    "id": "msg-123456"
  }
}

Usage Example:

POST

Inputs:

oauth_token (object, required) — Valid Google OAuth token object
message_id (string, required) — The message ID to modify
add_labels (array, optional) — Label IDs to add (default: [])
remove_labels (array, optional) — Label IDs to remove (default: [])

Output:

{
  "result": {
    "message": "Message labels updated",
    "id": "msg-123456",
    "labelIds": ["INBOX",

Inputs:

oauth_token (object, required) — Valid Google OAuth token object

Output:

{
  "result": {
    "count": 5,
    "labels": [
      { "id": "INBOX", "name": "INBOX", "type": "system" },
      { "id": "LABEL_1", "name":

Inputs:

oauth_token (object, required) — Valid Google OAuth token object
name (string, required) — Label name
label_list_visibility (string, optional) — Label visibility in list (default: "labelShow")
message_list_visibility (string, optional) — Label visibility in messages (default: "show")

Output:

{
  "result": {
    "message": "Label created successfully",
    "label": {
      "id": "LABEL_3",
      "name":

Inputs:

oauth_token (object, required) — Valid Google OAuth token object
label_id (string, required) — The label ID to delete

Output:

{
  "result": {
    "message": "Label deleted successfully",
    "id": "LABEL_3"
  }
}

Usage Example:

POST /mcp/cl-gmail/delete_label

Inputs:

oauth_token (object, required) — Valid Google OAuth token object
query (string, required) — Gmail search query (e.g., "from:sender@example.com is:unread")
max_results (integer, optional) — Maximum results to return (default: 10)

Output:

{
  "result": {
    "count": 3,
    "messages": [
      { "id": "msg-111", "threadId": "thread-1"

Inputs:

oauth_token (object, required) — Valid Google OAuth token object
message_id (string, required) — The message ID to mark as read

Output:

{
  "result": {
    "message": "Message marked as read",
    "id": "msg-123456"
  }
}

Usage Example:

POST

Inputs:

oauth_token (object, required) — Valid Google OAuth token object
message_id (string, required) — The message ID to mark as unread

Output:

{
  "result": {
    "message": "Message marked as unread",
    "id": "msg-123456"
  }
}

Usage Example:

POST

Inputs:

oauth_token (object, required) — Valid Google OAuth token object
thread_id (string, required) — The thread ID to retrieve
format (string, optional) — Response format: "full", "minimal", or "raw" (default: "full")

Output:

{
  "result": {
    "id": "thread-456",
    "historyId": "987654321",
    "messages": [
      { "id": "msg-111", "snippet":

Inputs:

oauth_token (object, required) — Valid Google OAuth token object
max_results (integer, optional) — Maximum drafts to return (default: 10)

Output:

{
  "result": {
    "count": 2,
    "drafts": [
      { "id": "draft-1", "message": { "id": "msg-001" } },
      { "id": "draft-2",

Inputs:

oauth_token (object, required) — Valid Google OAuth token object
to (string, required) — Recipient email address
subject (string, required) — Email subject line
body (string, required) — Email body content

Output:

{
  "result": {
    "message": "Draft created successfully",
    "id": "draft-3"
  }
}

Usage Example:

Reference & Support

Search Query Syntax

is:unread — Unread messages
is:read — Read messages
from:email@example.com — Messages from specific sender
to:email@example.com — Messages to specific recipient
subject:keyword — Messages with keyword in subject
has:attachment — Messages with attachments
before:2026-03-19 — Messages before date
after:2026-03-19 — Messages after date

Label Visibility Options

labelShow — Show label in label list
labelHide — Hide label in label list

All tools require a valid Google OAuth token. Here's how to obtain one:

Step 1: Create Google Cloud Project

Go to Google Cloud Console
Create a new project or select an existing one
Enable the Gmail API from the API Library

Step 2: Create OAuth 2.0 Credentials

Navigate to Credentials in Google Cloud Console
Click + Create Credentials → OAuth client ID
Select your application type (Desktop, Web, or other)
Download the credentials JSON file

Step 3: Authenticate with Google

Use your Google account to obtain the OAuth token. Refer to Google OAuth 2.0 Documentation for detailed authentication steps.

Step 4: Required Scopes

Ensure your OAuth token has these scopes:

https://www.googleapis.com/auth/gmail.readonly — Read-only access to Gmail
https://www.googleapis.com/auth/gmail.modify — Modify Gmail messages and labels
https://www.googleapis.com/auth/gmail.send — Send Gmail messages
— Compose Gmail messages as drafts

Missing or Invalid OAuth Token

Cause: OAuth token not provided in request or incorrect format
Solution:
1. Verify oauth_token parameter is present in request
2. Check token is valid and not expired
3. Obtain a fresh OAuth token from Google

Insufficient Permissions

Cause: OAuth token lacks required scopes for operation
Solution:
1. Verify token has all required scopes for the operation
2. Regenerate token with additional scopes if needed
3. Check Google Cloud project has Gmail API enabled

Insufficient Credits

Cause: API calls have exceeded your requests limits
Solution:
1. Check credit usage in your Curious Layer dashboard
2. Upgrade to a paid plan or add credits for higher limits
3. Contact support for credit adjustments

Malformed Request Payload

Cause: JSON payload is invalid or missing required fields
Solution:
1. Validate JSON syntax before sending
2. Ensure all required parameters are included (, , etc.)

Connect

Get connection URL

https://gateway.mewcp.com/google-gmail/mcp

Request Builder

import asyncio
from fastmcp import Client

# Real MewCP gateway URL for this server
GATEWAY_URL = "https://gateway.mewcp.com/google-gmail/mcp"
API_KEY = "YOUR_API_KEY"

headers={
    "Authorization": f"Bearer {API_KEY}"
}

async def main():
    
    client = Client(GATEWAY_URL, headers=headers)
    
    async with client:
        # Test the connection by pinging the server
        await client.ping()
        
        # List available operations
        tools = await client.list_tools()
        resources = await client.list_resources()
        prompts = await client.list_prompts()

        # Execute operations
        result = await client.call_tool("example_tool", {"param": "value"})
        print(result)

asyncio.run(main())

Gmail

Documentation

Overview

Tools

Reference & Support

Search Query Syntax

Label Visibility Options

Step 1: Create Google Cloud Project

Step 2: Create OAuth 2.0 Credentials

Step 3: Authenticate with Google

Step 4: Required Scopes

Missing or Invalid OAuth Token

Insufficient Permissions

Insufficient Credits

Malformed Request Payload

Overview

Tools

Reference & Support

Search Query Syntax

Label Visibility Options

Step 1: Create Google Cloud Project

Step 2: Create OAuth 2.0 Credentials

Step 3: Authenticate with Google

Step 4: Required Scopes

Missing or Invalid OAuth Token

Insufficient Permissions

Insufficient Credits

Malformed Request Payload

Message Output Formats

Resource Formats

Server Not Found

Authentication Token Invalid or Expired