← Back to Documentation

Gmail

Read, search, and send emails with AI assistance. Manage drafts, organize with labels, and handle attachments.

Tool Reference: 23 tools with full schemas →

Setup

Connect the Gmail toolkit to one or more Google accounts to allow your AI assistant to read, search, and send emails on your behalf.

Prerequisites

Before connecting Gmail, ensure you have configured an MCP server in your toolforest.io dashboard.

Setup Steps

Step 1: Connect a Google Account

1. Open Toolforest and go to Toolkits.
2. Select the Google Workspace tab.
3. Find Gmail.
4. Click Connect.
5. Choose the Google account you want this toolkit to use, or select Use another account.
6. You’ll be redirected to Google’s authorization page.

Important: The Google account you connect doesn’t need to match your toolforest.io email address.

Step 2: Authorize Permissions

Google will ask you to grant toolforest.io the following permissions:

• View your email messages and settings – Allows toolforest.io to read messages, threads, labels, and mailbox metadata
• See, edit, create, or change your email settings and filters in Gmail – Allows toolforest.io to manage labels and filters
• Manage drafts and send emails – Allows toolforest.io to create drafts and send messages on your behalf
• Read, compose, and send emails from your Gmail account – Allows toolforest.io to compose replies, forwards, and new emails

Check each box, then click Continue to grant these permissions.

Step 3: Confirmation

After authorizing, you’ll be redirected back to toolforest.io with a “Successful connection” message. The toolkit status will now show Connected.

Step 4: Optionally Connect Additional Accounts

The first connected Google account is marked as the default account for this toolkit. If you want to use another Google account as well, click Manage accounts next to the toolkit, then choose Add another Google account.

When your AI assistant calls a Gmail tool, the default account is used unless the tool call specifies a different account.

Understanding Permissions

What toolforest.io Can Access

toolforest.io’s permissions allow your AI assistant to:

• Read mail: Search messages, view threads, and download attachments
• Compose and send: Create new emails, reply, reply-all, and forward
• Manage drafts: Create, list, update, and send drafts
• Organize: Apply labels, mark read/unread, archive, star, or trash messages, and manage filters

Data Privacy

Your email data is retrieved only when you explicitly ask your LLM to query it. toolforest.io does not store your messages permanently; it acts as a bridge to fetch the specific information your assistant needs to answer your questions.

Security Code Handling

Gmail messages can contain login codes, password reset URLs, magic links, and other one-time credentials. By default, the Gmail toolkit redacts detected codes and links before message content is returned to your AI assistant. This helps protect you if an assistant, local agent, or connected app is compromised, or if a malicious email tries to use prompt injection to make the assistant reveal a code.

The filter uses a dynamic list of known security-code senders together with email text patterns for verification codes, one-time passwords, reset links, and similar sensitive content.

Step 1: Open Gmail Settings

In your MCP server panel, locate the Gmail toolkit. Click the ⋮ menu for the toolkit, then choose Settings.

Step 2: Choose Security Code Handling

Select one of the available options:

• Redact codes (recommended): Replace detected security codes, reset URLs, and similar sensitive values with the placeholder [REDACTED]; the rest of the message is returned.
• Withhold the whole message: If a message appears to contain a security code or reset link, the Gmail toolkit withholds that message entirely.
• Off: Return messages unmodified, including any detected security codes or reset links.

Step 3: Save

Click Save. The setting applies to Gmail across all of your sessions.

Managing Your Connection

Disconnect

To disconnect the toolkit:

1. Click Manage accounts next to the toolkit
2. Click Disconnect for the Google account you want to remove
3. To remove every connected account for the toolkit, disconnect each account in the list
4. toolforest.io will remove the stored access tokens for disconnected accounts

Revoke Permissions

To fully revoke toolforest.io’s access to your Google account:

• Visit your Google Account permissions page
• Find toolforest.io and click Remove Access

Capabilities