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 emails = await client.gmail.listEmails({});

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

Email Management

gmail_send_email - Send an email
gmail_list_emails - List emails in your inbox
gmail_get_email - Get a specific email
gmail_delete_email - Delete an email
gmail_search_emails - Search emails by query

Email Status

gmail_mark_as_read - Mark email(s) as read
gmail_mark_as_unread - Mark email(s) as unread

Labels

gmail_list_labels - List all labels
gmail_create_label - Create a new label

And More...

Use client.getEnabledTools() to see all available Gmail tools.

Examples

Send an Email

const result = await client.gmail.sendEmail({
  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 Emails

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

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

Search Emails

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

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

Create a Label

const result = await client.gmail.createLabel({
  name: "Projects/My Project",
  labelListVisibility: "labelShow",
  messageListVisibility: "show",
});

console.log("Label created:", result);

Mark as Read

const result = await client.gmail.markAsRead({
  messageIds: ["message-id-1", "message-id-2"],
});

console.log("Marked as read:", 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_emails 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 emails
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.sendEmail({
    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