How to connect Gmail to Claude Code

Short answer

Connect Gmail in Upsy, run claude mcp add --transport http --scope user upsy https://upsy.ai/connect, then sign in from /mcp. It takes about two minutes, works with a Claude plan or an API key, and needs no Google Cloud project. Upsy is free for personal use.

The built-in way

Claude Code has no Gmail of its own, and Anthropic's plugin marketplace has no Gmail plugin. Your other options:

• Claude's Gmail connector. If you log in to Claude Code with a Claude subscription, the connectors you added at claude.ai show up in /mcp on their own (Claude Code docs). Claude's Gmail connector searches, reads, sends, replies and forwards, but it sees only attachment metadata, not the files (Claude Help Center), and it holds one Google account at a time. It doesn't load when Claude Code runs on an API key, a third-party provider such as Amazon Bedrock, or CLAUDE_CODE_OAUTH_TOKEN.
• Google's Gmail MCP server, in Google's Workspace Developer Preview Program. It needs preview access, a Google Cloud project and your own OAuth client, and it searches, reads, labels and drafts but can't send (Google's setup guide).
• A self-hosted server such as google_workspace_mcp, run with an OAuth client from your own Google Cloud project. While that project's consent screen is External and in Testing, Google expires its refresh tokens after 7 days (Google's OAuth docs), so you sign in again weekly.

If one Gmail account inside Claude is enough, use Claude's connector. If your mail must stay on infrastructure you run, self-host. Upsy fits when you want several accounts, attachment contents, Read-only enforced on the server, a history of every action, or the same Gmail in Cursor and Codex. Protocol details and other clients are in the Gmail MCP server guide.

What you need

• Claude Code, logged in any way, and a free Upsy account.
• A Gmail or Google Workspace account. On Workspace, your admin may have to allow the app.

Connect Gmail to Claude Code

1. Go to upsy.ai and click Set up Upsy to create a free account.

2. Open Apps, choose Gmail and sign in with Google. Repeat for each address you want, up to five.

3. Optional: on the Assistants page, click Add assistant and pick Claude Code under Which assistant? to get these steps with the command to copy.

4. In your terminal, run:

   claude mcp add --transport http --scope user upsy https://upsy.ai/connect
   

   --scope user makes Upsy available in every project. Without it, Claude Code uses local scope, which covers only the folder you ran the command in.

5. Start claude, type /mcp, choose upsy and authenticate. From a shell, claude mcp login upsy does the same. Your browser opens an Upsy page.

6. Sign in to Upsy, tick Gmail, keep full access or switch it to Read-only, and click Allow. Back in the terminal, /mcp shows upsy as connected.

There's no API key or client secret anywhere. Claude Code registers itself with Upsy's OAuth server, then stores and refreshes the tokens itself.

Project scope (a team's .mcp.json) works too: the file holds only the address, and each teammate approves the server and signs in to their own Upsy.

Check that it works

Ask Claude Code:

Use upsy to list my five most recent unread emails, with sender and subject.

Claude Code asks to run mcp__upsy__search_threads (unless your permission mode allows it), searches with a query like is:unread, and prints the five threads. In Upsy, History lists the search under Claude Code.

What Claude Code can do with Gmail

Upsy's Gmail tools, which Claude Code names mcp__upsy__<tool>:

With Google Drive connected too, drive_upload copies an email's attachment into a Drive folder, and the file never passes through Claude.

On the Assistants page, each assistant gets one access level for Gmail: Full access, Read-only (only the "Yes" rows), Pick actions (the tools you choose, one by one) or No access. With several Gmail accounts, every tool takes an account argument with the address; without it, Upsy uses the first account you connected.

To skip Claude Code's prompt for reading but keep it for sending, add allow rules to ~/.claude/settings.json (permission rules):

{
  "permissions": {
    "allow": [
      "mcp__upsy__search_threads",
      "mcp__upsy__get_message",
      "mcp__upsy__email_read_thread"
    ]
  }
}

send_message isn't on the list, so Claude Code still asks before every send.

Prompts to try

• "Find emails from Stripe or Sentry this week about failed webhooks and list the error codes."
• "Read my latest thread with Ada about the API migration and draft a reply listing what changed in git log since v2.3. Don't send it."
• "Save the PDF attached to the newest invoice email into my Drive folder Receipts."
• "Search my work account for 'on-call handoff' in the last 7 days and summarize it in HANDOFF.md."

Troubleshooting

/mcp shows upsy as needing authentication

Choose upsy in /mcp and authenticate again (Re-authenticate if a refresh failed). If no browser opens, copy the URL Claude Code shows. If the page fails after Allow, paste the callback URL from the address bar into Claude Code.

Google's sign-in screen names Composio

While Google reviews Upsy's own Google app, Gmail signs in through Composio's verified Google app. You may see Composio on the consent screen, asking for full mail access. That's expected and temporary. Upsy acts on your email only when an assistant you allowed asks.

Error 400: access_not_configured on a work account

Your Google Workspace admin blocks apps it hasn't reviewed. The admin can trust the app under Security › Access and data control › API controls › Manage App Access in the Admin console (Google's guide).

A tool answers "The user hasn't allowed you to use Gmail"

Claude Code sees the Gmail tools even when Gmail is off for it, and calling one returns this. Turn Gmail on for Claude Code on Upsy's Assistants page, then reconnect upsy from /mcp. If the answer says Gmail isn't connected to Upsy, connect it under Apps.

Upsy works in one folder but not another

You added it with the default local scope. Run claude mcp remove upsy, then add it again with --scope user.

Long emails come back cut short

Upsy returns up to 30,000 characters of a message, or 8,000 per message in a thread, and marks the rest [truncated]. Claude Code also saves very large results to a file; MAX_MCP_OUTPUT_TOKENS sets that limit.

Security and privacy

• Claude Code never gets your Google password or tokens. It holds an Upsy token, calls Upsy's tools, and Upsy calls Gmail.
• With Read-only, the tools that send, change or delete aren't listed and can't be called, whatever permission mode Claude Code is in.
• Every action is in Upsy's History under Claude Code. Alerts email you when one assistant makes 50+ deletes, 20+ sends or 100+ reads from your apps within 10 minutes, and when a new assistant or app connects.
• Upsy has no approval step of its own. The confirmation before a send is Claude Code's permission prompt, so keep send_message out of your allow rules.
• One click on the Assistants page turns Claude Code off; claude mcp remove upsy also deletes its stored tokens.
• Upsy is built by Upstash, free for personal use, with no ads, and doesn't sell data.

FAQ

Is there a Gmail MCP server for Claude Code?

Not built in. Upsy is a hosted one you add with claude mcp add. Google's own is in developer preview and can't send.

Can Claude Code send emails?

Yes. With Gmail on Full access in Upsy, send_message sends a new email, a reply or a draft. Claude Code asks before each call unless you've allowed the tool.

Can I connect two Gmail accounts to Claude Code?

Yes. Connect up to five in Upsy, allow each one for Claude Code, and name the address in your prompt. The tools take an account argument.

Do I need a Google Cloud project?

No. Upsy handles the Google side. You'd need one only for Google's own server or a self-hosted one.

Does it work with an API key or Amazon Bedrock?

Yes. Upsy is an ordinary remote MCP server, so it works however Claude Code is logged in. Claude's claude.ai connectors don't.