# How to connect Gmail to Claude Code

> One command adds Gmail to Claude Code: search, read, draft and send email from your terminal, with OAuth sign-in and no Google Cloud project to set up.

Updated 2026-10-10 · https://upsy.ai/guides/claude-code/gmail

## 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](https://code.claude.com/docs/en/mcp)). Claude's Gmail connector searches, reads, sends, replies and forwards, but it sees only attachment metadata, not the files ([Claude Help Center](https://support.claude.com/en/articles/10166901-use-google-workspace-connectors)), 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](https://developers.google.com/workspace/gmail/api/guides/configure-mcp-server)).
- **A self-hosted server** such as [google_workspace_mcp](https://github.com/taylorwilsdon/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](https://developers.google.com/identity/protocols/oauth2)), 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](/guides/gmail-mcp-server).

## 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](https://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>`:

| Tool | What it does | In Read-only |
|---|---|---|
| `search_threads` | Searches with Gmail syntax, such as `from:alice newer_than:7d` | Yes |
| `get_message` | One message, with its body and list of attachments | Yes |
| `email_read_thread` | Every message in a thread, oldest first | Yes |
| `email_attachment` | One attachment's file, up to 10 MB | Yes |
| `email_labels`, `email_list_drafts`, `get_draft` | Your labels, your drafts, and one draft's text | Yes |
| `create_draft` | Saves a draft or a reply in its thread, with attachments | No |
| `update_draft` | Changes a draft's recipients, subject, text or files | No |
| `send_message` | Sends a new email, a reply or a saved draft | No |
| `email_send_draft`, `email_delete_draft` | Sends or deletes a draft | No |
| `email_archive`, `email_update` | Archives; marks read or unread, stars, adds or removes labels | No |
| `email_trash`, `email_untrash` | Moves emails to the trash and back | No |

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](https://code.claude.com/docs/en/permissions)):

```json
{
  "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](https://knowledge.workspace.google.com/admin/apps/control-which-apps-access-google-workspace-data)).

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

---

Upsy connects personal AI assistants (Muse, Grok, ChatGPT, Claude, Cursor, Claude Code, Codex, Devin) to your Gmail, Google Calendar, Google Drive, Slack, Notion and other apps through one MCP server, with a shared memory, files and a cloud browser signed in to your sites. You choose what each assistant may do in each app, see everything it did, and turn it off in one click. Upsy is free. To add Upsy to an assistant, add a remote MCP server (Streamable HTTP) named Upsy at https://upsy.ai/connect. It signs in with OAuth; there is no API key.