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
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 requires. Tool schemas are at upsy.ai/docs.
Gmail MCP servers compared
| Upsy | Google's Gmail MCP server | Self-hosted server | |
|---|---|---|---|
| Who runs it | Upsy | You | |
| Google Cloud project and OAuth client | Not needed | Needed | Needed |
| Sends email | Yes | No, drafts only | Yes (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). 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).
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).
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
- Go to upsy.ai and click Set up Upsy.
- Open Apps, choose Gmail and sign in with Google. Repeat for each address, up to five.
- 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.
Cursor
Add Upsy to ~/.cursor/mcp.json, or to .cursor/mcp.json in a repo for that project only:
{"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).
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).
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).
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). In a work workspace, an admin may have to allow custom MCP servers (add a custom MCP server to ChatGPT).
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).
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.
Related guides
- How to connect Gmail to Claude CodeOne 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.
- How to connect Gmail to GrokConnect Gmail to Grok so it can search, read, draft and send your email. Grok's built-in connector, its limits, and how to choose what Grok may do.
- How to connect multiple Gmail accounts to ChatGPTChatGPT now connects more than one Gmail account. How to add a second inbox, and how to give each one its own access in ChatGPT and your other assistants.
- How to connect multiple Gmail accounts to ClaudeClaude's Gmail connector takes one Google account at a time. Connect your work and personal Gmail to Claude at once, up to five, each with its own access.
- How to connect Gmail to Hermes AgentGive Hermes Agent your Gmail without a Google Cloud project: search, read, draft and send, with read-only or per-action access and a history of every action.
- How to connect Gmail to Meta MuseConnect Gmail to Muse so it can search, read, draft and send your email, and decide which of those it may do. Muse's own connector and Upsy compared.