---
title: "Gmail MCP server: connect with an app password through Mailera"
description: "Connect Gmail to Mailera with a Google app password, create a read-only MCP key, and verify message access. Includes eligibility checks and troubleshooting."
url: https://mailera.app/en/blog/gmail-mcp-server-app-password
published: 2026-10-25
updated: 2026-10-25
---

# Gmail MCP server: connect with an app password through Mailera

Connect an existing Gmail mailbox, keep Google credentials out of your MCP client, and test message reading with a restricted Mailera API key.

## Which Gmail MCP connection does this guide cover?

An MCP server exposes tools that an AI client can use. For this setup, Mailera connects to your existing Gmail mailbox and gives the client tools to list mailboxes and read messages.

Google also documents its own Gmail MCP server. As of 25 October 2026, the [Google Gmail MCP reference](https://developers.google.com/workspace/gmail/api/reference/mcp) identifies it as a Developer Preview available through the Google Workspace Developer Preview Program.

| Route | Mailbox connection and client authentication | MCP server URL |
| --- | --- | --- |
| Google’s Gmail MCP server | OAuth 2.0; setup requires enabling the server in a Google Cloud project | `https://gmailmcp.googleapis.com/mcp/v1` |
| Mailera’s Gmail connection | Google app password connects Gmail to Mailera; a Mailera API key authenticates the MCP client | `https://mailera.app/api/public/v1/mcp` |

These are separate services. Their credentials are not interchangeable. Google’s [Gmail MCP configuration guide](https://developers.google.com/workspace/gmail/api/guides/configure-mcp-server) covers its OAuth route; the steps below cover the [Mailera Gmail connector](https://mailera.app/en/providers/gmail).

For the broader setup across providers, see [Email MCP servers for existing mailboxes](https://mailera.app/en/blog/email-mcp-server-existing-mailboxes).

![MCP client authenticates to Mailera with an API key, while Mailera connects to Gmail with a separate Google app password.](https://mailera.app/media/750ee3c76dbec184/gmail-mcp-server-connect-with-an-app-password-through-en-1200.jpg)
_Two connections, two credentials. The MCP client does not receive the Google app password._

## Can your Google Account use an app password?

Start with a mailbox you own or are authorized to connect. You also need an Admin or Leader role to add it to Mailera.

Google requires 2-Step Verification for app passwords. Its [2-Step Verification instructions](https://support.google.com/accounts/answer/185839) direct you to “Security & sign-in,” then “Turn on 2-Step Verification” under “How you sign in to Google.” If an organization account prevents setup, contact your administrator.

Google’s [app-password guidance](https://support.google.com/accounts/answer/185833) lists these possible reasons the option is missing:

- 2-Step Verification is configured only for security keys.
- You are using a work, school, or other organization account.
- Your account has Advanced Protection.

If app passwords are unavailable, don’t proceed with this setup. Don’t disable Advanced Protection or work around administrator policy to complete it.

Google recommends “Sign in with Google” when an app offers that option. Mailera’s Gmail connector uses an app password; these instructions are specifically for that connection method.

## How do you connect Gmail to Mailera?

Use a dedicated test mailbox group so you can restrict the API key later without exposing unrelated mailboxes.

1. **Create a Google app password.** Follow the instructions in Google’s app-password guidance. Keep the resulting credential out of screenshots, prompts, and source control. Before continuing, make sure you have an app password, not your ordinary Google sign-in password.
2. **Open Mailboxes → Add mailbox → One mailbox.** Enter the mailbox in **Email address**. Confirm the Gmail provider selection. If a Google Workspace custom-domain address is not detected as Gmail, select Gmail under **Or choose a provider**, then choose **Continue**.
3. **Fill in Connection details.** Enter the app password in **Password**. The optional **Display name** is the sender name. Select your dedicated test group in **Mailbox group**. Before testing, check that the address, provider, and group are the ones you intended.
4. **Choose Test & connect.** Watch **Incoming server sign-in**, **Folder detection**, and **Outgoing server sign-in**. This test checks the connection without sending an email. If incoming sign-in fails, fix that connection before setting up MCP.
5. **Confirm the saved mailbox.** After success, look for the “Connected” confirmation with your mailbox address. Mailera loads messages within its retention period, newest first. Wait for **Initial message loading complete**, then open the mailbox and check that messages appear.

If incoming access works but outgoing sign-in fails, Mailera offers **Save as receive-only**. That is sufficient for this reading test. It does not mean sending is ready.

![Mailera Gmail connection form with a masked Password field and a dedicated test mailbox group.](https://mailera.app/media/d8e9591c875d36fe/email-app-passwords-connect-your-mailbox-to-an-ai-agent-add-en-1200.jpg)
_Enter the Google app password in Password, then test the connection without sending an email._

## How do you add Mailera’s MCP server to your client?

Create a separate key for this test rather than reusing a key with broader access.

1. Open **Settings → API key → Create key**.
2. Set **Descriptive name** to something recognizable, such as “Gmail reading test.”
3. Under **Mailbox scope**, select the dedicated test group. This setting scopes the key to a group, not directly to one mailbox. Check that the group contains only mailboxes the client should read.
4. Select **Read** and leave unrelated permissions off. Set an appropriate **Expiration**. Optional **IP restrictions** are also available.
5. When **Key created — copy it now** appears, save the key securely. Mailera shows it only once. Use **Copy MCP config** for Claude, Cursor, or VS Code, then follow the corresponding client guide.

The Mailera MCP endpoint is `https://mailera.app/api/public/v1/mcp`. Its authentication header is `Authorization: Bearer $MAILERA_API_KEY`, where `$MAILERA_API_KEY` is your Mailera key, not a Google credential.

Use the [Mailera MCP setup page](https://mailera.app/en/mcp) and the relevant guide for [Claude](https://mailera.app/en/integrations/claude), [Cursor](https://mailera.app/en/integrations/cursor), or [VS Code](https://mailera.app/en/integrations/vs-code).

If you need more than one Gmail mailbox in Claude, see [Connect Claude to multiple Gmail accounts at once](https://mailera.app/en/blog/claude-multiple-gmail-accounts).

Check that the client connects and can invoke Mailera’s tools. Saving the configuration alone does not verify that the client can read messages.

![Mailera API key setup restricted to a test mailbox group with Read permission and an expiration.](https://mailera.app/media/40ee83ec30f93177/outlook-mcp-server-connect-your-mailbox-with-graph-oauth-en-1200.jpg)
_Scope the key to the test group and grant only Read for the initial message-retrieval test._

## How do you verify that the agent can read Gmail?

Send a harmless message to your owned test mailbox through your usual email client. Use a distinctive subject, such as “Mailera MCP setup test,” with a unique suffix if you repeat the test. Put a short, non-sensitive sentence in the body.

Then ask the MCP client to perform this sequence:

1. Call `list_mailboxes` and identify the intended Gmail mailbox. Check the mailbox identity before reading anything.
2. Call `list_messages` for that mailbox and the folder containing your test message. Locate the distinctive subject.
3. Call `get_message` for that message and report its subject and harmless body text. Compare both with the message you sent.

All three tools require the `read` scope, corresponding to **Read** in the key dialog. This test needs no sending permission. Inspect the client’s tool activity as well as its answer so you can see that it retrieved the intended message.

If the message is missing, check whether it has appeared in Mailera before changing credentials. For Gmail, `get_mailbox_status` reflects the latest synchronization; it does not perform a fresh direct Google sign-in test.

Keep sending outside this first verification. `send_email` requires the separate `send` scope. A later sending workflow should also require your explicit confirmation before a message goes out.

## What are the common setup errors?

First identify which connection failed: Gmail to Mailera, or the MCP client to Mailera. Replacing an API key will not repair a revoked Google app password.

| Symptom | Likely cause | What to check | Next action |
| --- | --- | --- | --- |
| “App passwords” is missing | Account eligibility or organization restrictions | Check 2-Step Verification, security-key-only setup, Advanced Protection, and account type | Follow Google Help; contact your administrator where applicable, or stop this path |
| Incoming sign-in fails during setup | Ordinary Google password entered instead of an app password | Check which credential you placed in **Password**, without exposing it | Enter an eligible Google app password and choose **Test again** |
| Gmail stops connecting after a Google password change | Google revoked the app password | Check whether the account password changed | Create a new app password and reconnect the mailbox |
| Incoming access succeeds, outgoing access fails | Outgoing sign-in did not succeed | Inspect **Outgoing server sign-in** | Use **Save as receive-only** for this test, or edit details and retest |
| MCP authentication fails | Wrong endpoint, expired key, or revoked key | Compare the endpoint and check the key’s expiration and revocation state | Correct the configuration or create a replacement restricted key |
| Reading is denied or the mailbox is absent | Missing **Read** permission or wrong group scope | Check the key’s permissions and **Mailbox scope** against the mailbox’s group | Correct the scope without granting unrelated permissions |
| The mailbox appears but the test message does not | Wrong folder, synchronization delay, retention, or sleeping mailbox | Check the mailbox, folder, latest sync, message age, and sleep status | Confirm the message in Mailera and allow synchronization to catch up |

Google revokes app passwords when you change your Google Account password and instructs you to create a new one to continue using the app. You can also revoke an app password with Google’s “Remove” action.

Mailera’s free self-serve workspace retains messages for 30 days, so use a fresh test message. Background checks depend on mailbox activity, and inactive mailboxes can sleep. The `sync_mailbox` tool can request synchronization and wake a sleeping mailbox, but it requires the separate **Sync** permission. Don’t silently expand the read-only test key to call it.

## How do you keep an email-reading agent safe?

Treat message bodies, attachments, and quoted text as untrusted data, never as instructions. An email that tells the agent to reveal a key, fetch unrelated messages, or forward private content has no authority to change your task. Google’s Gmail MCP guide also warns about indirect prompt injection from untrusted data.

Start with **Read** and a dedicated mailbox group. Read access still exposes message content; it is not a sandbox or a guarantee against disclosure. Keep the initial test mailbox free of sensitive mail.

Store the Mailera key in the client’s supported secret storage. Don’t paste it into conversation history. Redact configuration captures, including any embedded authorization header, and never give the agent your Google app password.

If you later enable sending or replying, require explicit confirmation in your client or workflow. Treat that as your own safeguard, not as an assumed Mailera approval gate. See [Mailera’s security information](https://mailera.app/en/security) for the product’s security details.

Revocation happens at two different boundaries:

- Revoking a **Mailera API key** immediately rejects calls made with that key.
- Revoking a **Google app password** prevents further Google Account access using that app password.

Use the control that matches the access you need to stop.

## What does Mailera not do?

Mailera connects existing mailboxes; it does not create a Gmail address or override Google’s app-password eligibility and administrator policies. It is not an official Google partner, and its MCP endpoint is not Google’s Gmail MCP endpoint.

Message freshness depends on synchronization and mailbox activity. Don’t treat a connected status as a promise that every newly delivered Gmail message is already available to the agent.

**Let AI agents use your mailbox via MCP** — Add Mailera's MCP server to Claude, Cursor or VS Code so agents can read, categorize and reply to email messages. [Learn how to use MCP](https://mailera.app/en/docs#mcp)