Name: Integrate
Author: Integrate

The Gmail integration provides access to Gmail's API through the Integrate MCP server.

Installation

The Gmail integration is included with the SDK:

import { gmailIntegration } from "integrate-sdk/server";

Setup

1. Create Google OAuth Credentials

Go to Google Cloud Console
Create a new project or select an existing one
Enable the Gmail API
Create OAuth 2.0 credentials
Note your Client ID and Client Secret

2. Configure the Integration on Your Server

Add the Gmail integration to your server configuration. The integration automatically reads GMAIL_CLIENT_ID and GMAIL_CLIENT_SECRET from your environment variables:

import { createMCPServer, gmailIntegration } from "integrate-sdk/server";

export const { client: serverClient } = createMCPServer({
  apiKey: process.env.INTEGRATE_API_KEY,
  integrations: [
    gmailIntegration({
      scopes: [
        // Optional - defaults are provided
        "https://www.googleapis.com/auth/gmail.send",
        "https://www.googleapis.com/auth/gmail.readonly",
      ],
    }),
  ],
});

You can override the environment variables by passing explicit values:

gmailIntegration({
  clientId: process.env.CUSTOM_GMAIL_ID,
  clientSecret: process.env.CUSTOM_GMAIL_SECRET,
  scopes: ["https://www.googleapis.com/auth/gmail.send"],
});

3. Client-Side Usage

The default client automatically includes all integrations. You can use it directly:

import { client } from "integrate-sdk";

await client.authorize("gmail");
const messages = await client.gmail.listMessages({});

If you're using a custom client, add the integration to the integrations array:

import { createMCPClient, gmailIntegration } from "integrate-sdk";

const customClient = createMCPClient({
  integrations: [gmailIntegration()],
});

Configuration Options

Prop

Type

Available Tools

Messages

gmail_send_message - Send an email message
gmail_list_messages - List messages in your mailbox
gmail_get_message - Get a specific message
gmail_search_messages - Search messages with Gmail query syntax

Examples

Send a Message

const result = await client.gmail.sendMessage({
  to: "recipient@example.com",
  subject: "Hello from Integrate SDK",
  body: "This email was sent using the Integrate SDK!",
  cc: ["cc@example.com"],
  bcc: ["bcc@example.com"],
});

console.log("Email sent:", result);

List Messages

const result = await client.gmail.listMessages({
  maxResults: 10,
  labelIds: ["INBOX"],
  includeSpamTrash: false,
});

console.log("Emails:", result);

Get a Message

const result = await client.gmail.getMessage({
  id: "message-id-1",
  format: "full",
});

console.log("Message:", result);

Search Messages

const result = await client.gmail.searchMessages({
  query: "from:sender@example.com subject:important",
  maxResults: 20,
});

console.log("Search results:", result);

OAuth Scopes

The default scopes provide common Gmail access. You may need additional scopes:

https://www.googleapis.com/auth/gmail.send - Send email
https://www.googleapis.com/auth/gmail.readonly - Read email
https://www.googleapis.com/auth/gmail.modify - Modify email
https://www.googleapis.com/auth/gmail.labels - Manage labels
https://mail.google.com/ - Full Gmail access

Gmail Search Queries

The gmail_search_messages tool supports Gmail's search syntax:

from:sender@example.com - From specific sender
to:recipient@example.com - To specific recipient
subject:keyword - Subject contains keyword
has:attachment - Has attachments
is:unread - Unread messages
after:2024/01/01 - After specific date
newer_than:7d - Newer than 7 days

Combine with operators:

from:sender@example.com OR from:other@example.com
subject:urgent AND is:unread

Error Handling

try {
  const result = await client.gmail.sendMessage({
    to: "recipient@example.com",
    subject: "Test",
    body: "Test email",
  });
} catch (error) {
  if (error.message.includes("authentication")) {
    console.error("Authentication failed - check OAuth credentials");
  } else if (error.message.includes("quota")) {
    console.error("Gmail API quota exceeded");
  } else {
    console.error("Unexpected error:", error);
  }
}

Next Steps

Learn about the GitHub Integration
Configure Additional Integrations
See Advanced Usage for more examples

Gmail

On this page