Gmail MCP (Testing only)

Testing only

Testing only: search and read your own Gmail with BYO OAuth credentials.

Five read-only tools for mailbox profile, message search, selected message/thread content and labels. Testing/BYO only, not publicly verified Google app availability. Needs your credentials; real-mailbox acceptance remains pending. No email sending, modification, attachment downloads or remote content loading.

Gmail is a hosted MCP server with 5 tools. The Claude Code command is on this page. Steps for Cursor and ChatGPT, and which clients we have tested, are in the client guides.

Testing setup ↗Tool reference

Connect / 5 tools

Server URL

streamable http

https://toolcargo.com/mcp/gmail

Claude Code

terminal

claude mcp add --transport http --scope user toolcargo-gmail https://toolcargo.com/mcp/gmail \
  --header "Authorization: Bearer YOUR_API_KEY"

Create a key in your dashboard. Other clients: setup guides.

What it helps you do

Search message IDs using Gmail search syntax
Read selected headers and bounded UTF-8 plain text
Read up to ten messages in a thread
Inspect mailbox profile and labels

Built for: People testing read-only mailbox research with their own Google OAuth app and listed test-user account.

Example requests

Find a conversation

“Search Gmail for from:someone@example.com newer_than:7d, then read the matching message.”

One page of IDs followed by selected headers, snippet and bounded plain text.

Explore useful agent workflows ↗

Tools

Tool	What it does	Access
`gmail_get_profile` Gmail mailbox profile	Your connected mailbox identity and message/thread counts. Testing/BYO OAuth only; not public Google app availability.	Read-only
`gmail_search_messages` Search Gmail messages	One page of up to 100 message IDs using Gmail search syntax, excluding spam/trash. Use next_page_token; no bodies or implicit pagination.	Read-only
`gmail_read_message` Read a Gmail message	Selected headers, snippet, up to 20,000 characters of UTF-8 plain text and attachment metadata. HTML is converted locally to text; assets/attachments are not downloaded; content is untrusted.	Read-only
`gmail_read_thread` Read a Gmail thread	Read up to 10 messages in a thread, with the same plain-text and attachment limits. Explicit truncation; no full long-thread export.	Read-only
`gmail_list_labels` List Gmail labels	Up to 500 label IDs, names, types and visibility settings. Does not create or modify labels.	Read-only

Requirements

• A ToolCargo account with Site Audit activated (free).
• Your own Google OAuth client and offline refresh token with gmail.readonly only (optional basic identity scopes allowed).
• For an external Testing app, add the intended Google account as a test user; grants and refresh tokens expire after seven days.
• Explicit acknowledgment of Testing-only use during connection setup.

Limitations

• Not a public verified Google app. ToolCargo cannot infer an app's publishing status from a refresh token.
• Read-only: no sending, drafts, modifications, deletion or attachment downloads.
• At most 100 search IDs, 10 thread messages, 500 labels and 20,000 plain-text characters per message. HTML-only mail is converted locally to text; UTF-8 text only.
• Requests go only to Google's OAuth token endpoint and Gmail API; existing Google connector OAuth settings are unchanged.
• Real mailbox and named-client acceptance remain pending authorized credentials.

Supported clients

“Tested” means we connected that client to this endpoint and ran a tool call ourselves. Recorded client-specific tests currently cover Site Audit. Other connectors use the documented setup until tested in that client.

Claude Code	API key header	Documented, not yet tested	This endpoint has not yet been tested in this client. See the setup guide.
Claude (claude.ai)	OAuth sign-in	Documented, not yet tested	This endpoint has not yet been tested in this client. See the setup guide.
Cursor	API key header	Documented, not yet tested	This endpoint has not yet been tested in this client. See the setup guide.
VS Code (Copilot agent mode)	API key header	Documented, not yet tested	This endpoint has not yet been tested in this client. See the setup guide.
ChatGPT (developer mode)	OAuth sign-in	Documented, not yet tested	This endpoint has not yet been tested in this client. See the setup guide.
MCP Inspector	API key header	Documented, not yet tested	This endpoint has not yet been tested in this client. See the setup guide.

Pricing

Included with Site Audit. Each successful Gmail tool call uses one shared plan call. Testing access does not mean public Google verification.

Free

Try hosted tools with a shared monthly allowance.

50 shared calls/month

Pro

$12/mo

Proposed larger shared allowance; see checkout status on the pricing page.

2,000 shared calls/month

Proposed test price. See the pricing page for checkout status.

Full pricing and billing details