Set-up guide
Connect Gmail to Claude with an app password.
Two minutes, if Google shows you the app password setting. This guide also covers the case where it refuses to, which is more common than it looks and is never explained where you meet it.
- Time About 2 minutes
- You will need An app password
- IMAP setting Nothing to switch on
The short version
Create an app password in your Google Account, then paste it into the control panel with your Gmail address. If the app password page tells you the setting is not available, jump to the section on that: the cause is almost never what the message suggests.
Mechanics
Why Gmail needs an app password
Once an account has 2-Step Verification switched on, your ordinary Google password stops being enough on its own: anything signing in also needs the second factor, and a mail connection has no way to prompt you for a code.
An app password is Google's answer. It is a sixteen character password that stands in for your real one, is tied to your account, and can be revoked on its own at any moment without changing your Google password or disturbing anything else you are signed in to.
That revocability is the point, and it is why this is a better arrangement than it first appears. If you ever want to disconnect Mailbox MCP, you delete that one app password in your Google Account and access ends immediately, from your side, without asking us.
Before you start
What you need before you start
Two of these six rows are things other guides will tell you to do that you should not.
- A Gmail or Workspace account any plan
- 2-Step Verification, switched on phone or authenticator
- An app password 16 characters
- IMAP enabled in Gmail settings always on since Jan 2025
- Your normal Google password never asked for
- Time to allow about 2 minutes
Walkthrough
Connect Gmail, step by step
-
Check how your 2-Step Verification is backed
Open your Google Account, go to Security, and look at 2-Step Verification. You are checking for one thing: that it lists a phone number or an authenticator app.
Do this first even though it feels like a detour. It is the single thing that decides whether the next step works, and checking it now takes ten seconds where discovering it later costs an hour.
-
Create an app password
Go to the app passwords page in your Google Account. Give the password a name you will recognise in a year, such as Mailbox MCP, and create it.
Google shows the sixteen characters once. Copy them before closing the dialog. If you lose it, nothing is broken: delete that app password and make another.
If the page will not let you
If you are told the setting is not available for your account, do not start changing security settings at random. The next section explains what is actually happening, and the fix is small.
-
Paste it into Mailbox MCP
In the control panel choose Add mailbox, pick Gmail, enter your Gmail address, and paste the app password. Google displays it in four groups of four; the spaces make no difference either way.
-
Check the connection
Ask Claude to list your five most recent messages. If they are the messages you expect, you are connected, and reading them has not marked anything as read.
The trap
When Google will not show you the app password setting
The short version is below. There is also a full write-up of this one error, covering the three other reasons the option can be missing and what to do about each.
You go to create an app password, and Google tells you:
The setting that you are looking for is not available for your account
That message is doing a poor job of explaining itself, and the usual guesses are all wrong. It does not mean app passwords are disabled, that your account is too new, that you need to wait, or that 2-Step Verification is off.
What it actually means
App passwords require 2-Step Verification backed by a phone number or an authenticator app. Google's own documentation puts it as the option being unavailable when 2-Step Verification is set up only for security keys, and the same is true of a passkey: both replace the whole sign-in rather than adding a second step to it, so neither unlocks app passwords.
The part that costs people the afternoon is that your account will happily report 2-Step Verification as ON throughout. It is on. It is simply on in a way that does not satisfy this particular requirement, and nothing on either screen says so.
So you can be looking at a security page that says everything is switched on, and at a message telling you a setting is unavailable, and both are correct at the same time. That contradiction is the whole problem.
Why this is now the common case
Google steers new accounts towards passkeys, and passkeys are genuinely the better way to protect an account day to day. The side effect is that a growing number of accounts satisfy 2-Step Verification in a way that does not unlock app passwords. This is the default route into the dead end rather than an unusual one.
The fix
Add a phone number or an authenticator app to 2-Step Verification in your Google Account. You are not removing your passkey and you are not making your account less safe: you are adding a second method alongside it. Once one of those exists, the app passwords page appears.
If you are on a Workspace account
There is a second, separate cause worth knowing about. A Google Workspace administrator can switch app passwords off for the whole organisation. If your account is managed by an employer or a school, and your 2-Step Verification does list a phone or an authenticator, this is the likely answer and only an administrator can change it.
Provider change
Do not go looking for the IMAP setting
Nearly every Gmail connection guide begins by telling you to open Gmail settings, find Forwarding and POP/IMAP, and enable IMAP.
Google removed that toggle in January 2025. IMAP is now always on for every Gmail account, and there is nothing to switch. If you go looking for it you will not find it, and the reasonable conclusion after five minutes of searching is that something is wrong with your account, which is exactly the wrong conclusion.
Any guide still carrying that step was written before the change and has not been revisited since. It is a useful test of whether the rest of what you are reading has been checked recently.
Troubleshooting
If something goes wrong
The app password is rejected
Check you pasted the app password rather than your ordinary Google password: they look nothing alike, but the field accepts either and only one of them works. If it still fails, delete that app password in your Google Account and create a new one. Copying from Google's dialog occasionally picks up a stray character.
You want to disconnect
Delete the app password in your Google Account. Access ends immediately and you do not need to tell us, ask us, or wait for us. Removing the mailbox in the control panel does the same thing from this side, and doing both is reasonable.
Your account uses Advanced Protection
Google's Advanced Protection Programme blocks app passwords by design. It is aimed at people at high risk of targeted attack, and if you are enrolled in it deliberately then this connection is not available to you, which is the programme working as intended rather than a fault.
The diary
Google Calendar connects too, and it is its own sign-in
The app password you have just made is a mail credential. It opens IMAP and SMTP and nothing else, which is the whole reason it is safe to hand over: it cannot reach your Drive, your contacts or your diary even if something tried. So a Google calendar is a second permission rather than one more box on the same one, and there is a button for it in the control panel next to the mailbox you just connected.
That is worth one more sentence, because the obvious workaround does not work and it is better to say so than to let somebody spend an evening on it. Google runs a CalDAV endpoint, the same protocol every other calendar here connects with. It refuses the app password. There was never an address to paste that would have worked, which is why this route is a sign-in and not a field.
What connecting it looks like
Press Connect Google Calendar, choose an account, and Google shows you exactly what is being asked for before you approve anything. The permission covers the diary and never the mail, you can withdraw it from your Google account whenever you like, and disconnecting it here hands it back rather than leaving it on your account page for years. Nothing about how your mail is opened changes.
The Google account does not have to be the mailbox address. Plenty of people keep the diary and the mail in different places, and a personal Gmail mailbox alongside a Workspace calendar is an ordinary arrangement rather than an edge case. The control panel shows you which account the calendar came back as, so picking the wrong one in Google's chooser is something you find out immediately instead of a fortnight later.
One thing to expect while you are there. Our Google verification is submitted and under review, so Google currently shows a screen saying it has not verified this app, with the way past it behind the Advanced link. That screen is about our review status rather than about what the permission does, and the permission it is guarding is the one described above.
What your assistant can then do with the diary
Read the week and search it by subject, location or organiser. Open one event with everybody who was invited and how each of them answered. Ask when a group of people are free and get back busy blocks rather than the contents of their diaries. Book your own time, move it, repeat it weekly. Invite people to a meeting, reschedule it and tell everybody, or cancel it with a message. Accept, tentatively accept or decline an invitation that has come in.
A recurring meeting appears on every date it falls on rather than once as a rule nobody can read, times come back in your calendar's own timezone rather than assumed, and somebody whose calendar cannot be read comes back as unknown and never as free. That last one is the distinction that decides whether a meeting gets booked over their afternoon.
Three things Outlook does that Google has no equivalent of
These are absent on this route rather than offered and refused, which is the same rule the rest of this product follows. Declining with a counter-proposal is a structured message in Outlook that the organiser accepts or rejects; Google has no public API for one, and emailing the organiser instead would have an assistant report a proposal nobody will ever see. Forwarding an invitation means something different on Google: adding somebody to the attendee list makes you appear to have invited them, and on an event you do not organise it is usually refused outright.
The out-of-office is the one most worth knowing about, because Google Calendar has something called an out-of-office event and it is not what you would assume. It declines meetings and emails nobody. The actual equivalent of an Outlook automatic reply is Gmail's vacation responder, which lives behind a restricted Google permission requiring an annual third-party security assessment, so it is not something we hold. An assistant that quietly set a calendar event when you asked for an out-of-office would leave you looking rude to everybody who wrote while you were away, and neither you nor we would see it happen.
There is one more case worth expecting: if you untick a box on Google's consent screen, the tools that needed it are absent afterwards rather than present and failing. If something you wanted is missing, connect the calendar again and leave everything ticked.
How to connect a calendar, on all three routes, and what an assistant can safely be trusted with once one is connected.
Limits
What this connection does not do
-
One mailbox each
One connection is one mailbox. Aliases send fine; a separate account needs its own connection.
-
No contacts, no Drive
An app password opens the mail and nothing else in your Google account, so there is no contacts list and no Drive on this connection. The diary is not part of it either, and has a sign-in of its own. A mailbox with no calendar connected is handed no calendar tools rather than tools that would refuse.
-
Labels read as folders
Gmail labels are read as folders, and a message in several labels appears in each.
-
10 MB a message
Attachments are capped at 10 MB a message in total, not per file, and the ceiling is ours rather than Google's. A file in your mailbox can use all of it; one the assistant writes itself is far smaller.
-
A file the assistant writes itself
Only a file the assistant composes itself is small. Files already in the mailbox, at a web address, or uploaded through a one-off link are streamed at send time and never pass through the model.
Attribution
Sources
- Google Account Help: sign in with app passwords What an app password is, and the 2-Step Verification requirement.
- Gmail Help: check Gmail through other email platforms The current IMAP instructions, which no longer include a toggle.
- Google Account Help: Advanced Protection Programme Why app passwords are unavailable on enrolled accounts.
Connect a Gmail mailbox.
The free tier is 5 calls a day on any mailbox. Revoking access is one click in your own Google Account, which is a reasonable thing to check before you commit to anything.