Gmail MCP server: connect with an app password through Mailera

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 identifies it as a Developer Preview available through the Google Workspace Developer Preview Program.

These are separate services. Their credentials are not interchangeable. Google’s Gmail MCP configuration guide covers its OAuth route; the steps below cover the Mailera Gmail connector.

For the broader setup across providers, see Email MCP servers for existing mailboxes.

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 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 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.

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 and the relevant guide for Claude, Cursor, or VS Code.

If you need more than one Gmail mailbox in Claude, see Connect Claude to multiple Gmail accounts at once.

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

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.

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 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.