# Gmail MCP server: connect Gmail to any AI agent

> A hosted Gmail MCP server with OAuth and no API keys. Connect Gmail to Claude, ChatGPT, Cursor, Codex or any MCP client, and choose what each may do.

Updated 2026-10-10 · https://upsy.ai/guides/gmail-mcp-server

## Short answer

Upsy is a hosted Gmail MCP server (a connector that lets an AI agent use your Gmail) at `https://upsy.ai/connect`. Connect Gmail in Upsy, add the address to your client, and sign in with OAuth: no API key, no Google Cloud project. It takes a few minutes in Claude Code, Cursor, Codex, Claude, ChatGPT or any client with remote MCP and OAuth, and it's free for personal use.

## Server details

| | |
|---|---|
| Address | `https://upsy.ai/connect` |
| Transport | Streamable HTTP |
| Sign-in | OAuth 2.1 authorization code with PKCE (`S256`). Public clients: no client secret, no API key |
| Client registration | Client ID Metadata Documents, or dynamic client registration at `https://upsy.ai/api/oauth/register` (30 an hour from one IP address) |
| Metadata | `https://upsy.ai/.well-known/oauth-authorization-server` and `https://upsy.ai/.well-known/oauth-protected-resource/connect` |
| Tokens | Access tokens last 15 minutes, refresh tokens 30 days |

A request without a token gets `401` with a `WWW-Authenticate` header whose `resource_metadata` points to the protected-resource document, as the [MCP authorization spec](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization) requires. Tool schemas are at [upsy.ai/docs](https://upsy.ai/docs).

## Gmail MCP servers compared

| | Upsy | Google's Gmail MCP server | Self-hosted server |
|---|---|---|---|
| Who runs it | Upsy | Google | You |
| Google Cloud project and OAuth client | Not needed | Needed | Needed |
| Sends email | Yes | No, drafts only | Yes ([google_workspace_mcp](https://github.com/taylorwilsdon/google_workspace_mcp)) |
| Gmail accounts | Up to 5 in one server | One per connection | Depends on the server |
| Access per client | Full access, Read-only, Pick actions or No access, set in Upsy | The OAuth scopes you configure | The server's flags, such as read-only mode |
| Record of actions | History and alerts | Admins' OAuth log events | Your own logs |

Google's server needs the Developer Preview Program, the Gmail API and Gmail MCP API turned on, a consent screen with `gmail.readonly` and `gmail.compose`, and a web OAuth client ([Google's setup guide](https://developers.google.com/workspace/gmail/api/guides/configure-mcp-server)). Self-hosted servers need a similar client; while it's External and in Testing, Google expires its refresh tokens after 7 days ([Google's OAuth docs](https://developers.google.com/identity/protocols/oauth2)).

When an alternative fits better:

- **Google's server**, if you're in the preview, drafts are enough, and you want only Google between your agent and your mail.
- **A self-hosted server**, if your mail must stay on infrastructure you run.
- **Your assistant's own Gmail connector**, if one account in one assistant will do. Claude's reads no attachment contents ([Claude Help Center](https://support.claude.com/en/articles/10166901-use-google-workspace-connectors)).

## What you need

A free Upsy account, a Gmail or Google Workspace account (on Workspace, your admin may have to allow the app), and an MCP client that supports remote servers with OAuth.

## Connect Gmail to Upsy

1. Go to [upsy.ai](https://upsy.ai) and click **Set up Upsy**.
2. Open **Apps**, choose Gmail and sign in with Google. Repeat for each address, up to five.
3. On the **Assistants** page, click **Add assistant** and choose your client under **Which assistant?** for its exact steps.

## Add the server to your client

Signing in opens an Upsy page: tick Gmail, keep full access or pick **Read-only**, and click **Allow**.

### Claude Code

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

Then run `/mcp`, choose upsy and sign in. Scopes and permission rules are in [connect Gmail to Claude Code](/guides/claude-code/gmail).

### Cursor

Add Upsy to `~/.cursor/mcp.json`, or to `.cursor/mcp.json` in a repo for that project only:

```json
{"mcpServers":{"upsy":{"url":"https://upsy.ai/connect"}}}
```

Then connect upsy where Cursor lists its MCP servers: Customize in the sidebar in current versions, Cursor Settings › MCP in older ones ([Cursor docs](https://cursor.com/docs/context/mcp)).

### Codex

```
codex mcp add upsy --url https://upsy.ai/connect
codex mcp login upsy
```

Codex saves it in `~/.codex/config.toml`, shared by its CLI and IDE extension ([OpenAI docs](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)).

### Claude

In Claude, open Customize › Connectors and click **Add custom connector**. Paste the address, click **Add**, then **Connect**. The Free plan allows one custom connector; on Team and Enterprise, an Owner adds it first ([add a custom connector to Claude](/guides/claude/custom-connector)).

### ChatGPT

In ChatGPT, open Plugins, click the plus button and add a custom MCP server. Name it Upsy, paste the address, set authentication to OAuth, accept the warning and create it as a plugin ([OpenAI docs](https://developers.openai.com/plugins/deploy/connect-chatgpt)). In a work workspace, an admin may have to allow custom MCP servers ([add a custom MCP server to ChatGPT](/guides/chatgpt/custom-connector)).

### Any other client

Add a remote MCP server named Upsy with the address above, Streamable HTTP and OAuth, with no key. Grok and Muse add it from chat: paste the setup prompt Upsy shows and approve the sign-in.

## Check that it works

Ask your agent:

> List what you can use in Upsy, then show my three most recent emails.

It should call `upsy_connectors`, which lists your Gmail addresses and its access to each, then `search_threads`. Both calls show up in Upsy's History.

## Gmail tools

Labels come from each tool's MCP annotations: **Read** (`readOnlyHint: true`), **Write** (`destructiveHint: false`) and **Sensitive write** (`destructiveHint: true`: it sends, deletes or can't be undone).

| Tool | What it does | Label |
|---|---|---|
| `search_threads` | Gmail search syntax, such as `from:alice newer_than:7d` | Read |
| `get_message` | One message; `FULL` adds its body and attachments | Read |
| `email_read_thread` | Every message in a thread | Read |
| `email_attachment` | One attachment, up to 10 MB | Read |
| `email_labels`, `email_list_drafts` | Labels; drafts with their ids | Read |
| `create_draft` | A draft or a reply, with up to 24 MB of attachments | Write |
| `email_archive`, `email_untrash` | Archive; restore from the trash | Write |
| `email_update` | Read or unread, star, important, labels, back to the inbox | Sensitive write |
| `email_trash` | Move to the trash (Gmail deletes after 30 days) | Sensitive write |
| `send_message` | Send a new email, a reply, or a draft by its id | Sensitive write |
| `email_send_draft`, `email_delete_draft` | Send or delete a draft | Sensitive write |

With Google Drive connected, `drive_upload` takes `from_email` to copy an attachment into Drive without it passing through the model.

## Access levels and accounts

Each client gets its own level for Gmail on the Assistants page: **Full access**, **Read-only** (the Read tools), **Pick actions** (the tools you choose) or **No access**. A tool the level doesn't allow isn't listed and can't be called.

You can connect up to 5 Gmail accounts and allow each on its own. With more than one, every tool takes `account`, the address to act as; the default is the first you connected.

## Troubleshooting

### The client stops at 401

That's the normal first response, and the client should start OAuth from the `WWW-Authenticate` header. If it doesn't, start the sign-in by hand: `/mcp` in Claude Code, `codex mcp login upsy` in Codex.

### Registration is refused

Upsy allows 30 dynamic client registrations an hour per IP address, which scripts that re-add the server can hit.

### Google's consent screen names Composio

While Google reviews Upsy's own Google app, Gmail signs in through Composio's verified Google app, so you may see Composio asking for full mail access. It's temporary. Upsy acts on your email only when an agent you allowed asks.

### `Error 400: access_not_configured`

Your Workspace admin blocks unreviewed apps. They can trust the app under Security › Access and data control › API controls › Manage App Access ([Google's guide](https://knowledge.workspace.google.com/admin/apps/control-which-apps-access-google-workspace-data)).

### A tool answers "Gmail isn't connected to Upsy"

Connect Gmail under Apps. If it says you haven't allowed it, turn Gmail on for that agent on the Assistants page, then reconnect the client.

## Security and privacy

- Agents never get your Google password or tokens: they call Upsy's tools, and Upsy calls Gmail.
- Every call is in Upsy's History under the agent that made it. Alerts email you when one agent makes 50+ deletes, 20+ sends or 100+ reads from your apps within 10 minutes, and when a new agent or app connects.
- Upsy has no approval prompt of its own; confirmation before a send comes from the client. Since an email can carry instructions aimed at your agent, keep sends confirmed, or give agents that read untrusted mail Read-only.
- One click turns an agent off. Upsy is built by Upstash, free for personal use, with no ads, and doesn't sell data.

## FAQ

### What is the Gmail MCP server URL?

Upsy's is `https://upsy.ai/connect`, over Streamable HTTP with OAuth. Google's preview server is `https://gmailmcp.googleapis.com/mcp/v1`.

### Is there an official Gmail MCP server from Google?

Yes, in developer preview. It needs preview access and your own Google Cloud OAuth client, and it drafts but can't send.

### Can a Gmail MCP server send email?

Upsy's can, with `send_message` and `email_send_draft`, when the agent has Full access or those tools picked. Google's preview server only creates drafts.

### How do I use Gmail MCP with Codex?

Run the two `codex mcp` commands above and allow Gmail on Upsy's page.

### Does Gmail MCP work with Claude?

Yes: with `claude mcp add` in Claude Code, and as a custom connector in Claude on the web and desktop.

---

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.