send_emailLABSCO SUMMARY
Three tools, and the batch search is the one that earns its place.
Putting two questions to a mailbox in one call, with the results sectioned per query, is faster than two round trips and reads better in a conversation. Every result carries a direct Gmail link, so checking an answer is a click.
What it is
A small Gmail server with three tools: send a message with optional attachments, search the mailbox with one query or several at once, and read a message in full. It runs against the Gmail API when an authorised token is present and falls back to SMTP and IMAP with an app password when it is not.
What you get
- A message sent with
to,subject,body, and optionalcc,bcc, an HTML body and local file attachments — unreadable files are skipped with a warning rather than failing the whole send (send_email) - The mailbox searched with a single query or a list of them, with
max_resultsapplied per query and the results sectioned per query (search_emails) - A direct Gmail web URL on every result and at the top of every message read, so an answer can be checked in one click (
search_emails,read_email) - A message read in full by the hex identifier the search returned (
read_email) - Batch search done in a single HTTP round trip on the API backend, where the IMAP backend iterates instead
- The backend chosen at startup and printed, so
backend=apiorbackend=imapis visible rather than guessed at
Requirements
uv, and one of two credentials. For the API backend: a Google Cloud OAuth client of type Desktop app, authorised once through the browser with the gmail.modify scope, which writes a refresh token to ~/.config/claude-gmail-mcp/token.json with 600 permissions. For the fallback: GMAIL_ADDRESS and GMAIL_APP_PASSWORD. Selection is by precedence at startup — a token file wins, then the two environment variables, and with neither the tools return an error. To force the fallback while a token file exists, point GMAIL_TOKEN_PATH at a path that does not exist.
Setup effort
One command, then sign in — uvx claude-gmail-mcp, then approve the OAuth sign-in
USE CASES
01
Sending an email without leaving the terminal
Say who it goes to, what it says, and what to attach. Local files go along with it, and one unreadable path warns instead of aborting the send.
02
Finding a message you half remember
Search with the same query syntax you would type into Gmail and get results back with a direct link on each. The link is what turns a plausible answer into a verified one.
03
Comparing two mailbox queries side by side
Pass both queries in one call — unread from one person, unread from another — and get the results sectioned per query. On the API backend that is a single round trip.
04
Reading a message a search turned up
Take the hex identifier from the search result and read the message in full, with the Gmail URL at the top so you can open the original alongside it.
05
Setting it up without a Google Cloud project
Use a Gmail app password and two environment variables instead. Batch search then iterates rather than batching, but nothing else changes about how you use it.
3 tools
Listed in project docs. Your client may show a different list.
search_emailsread_emailBEFORE YOU INSTALL
What to know first
Tools you get
3 tools named in the project's documentation.
Requires
- uvx on PATH
- One of: a Google Cloud OAuth client (Desktop app) for the Gmail API backend, or GMAIL_ADDRESS and GMAIL_APP_PASSWORD (a Gmail app password) for the SMTP/IMAP backend
INSTALLATION
Connect your client
Server setup
TERMINAL
uvx claude-gmail-mcpMCP Clients
Claude Code — Gmail API
In Google Cloud Console, create a project, enable the Gmail API and configure the OAuth consent screen (External, with your Gmail added as a test user). Create an OAuth client of type Desktop app and download the credentials JSON.
Run the auth helper on that file. A browser opens: sign in and approve; the refresh token is saved to ~/.config/claude-gmail-mcp/token.json.
CLAUDE CODE — GMAIL API · TERMINAL
uvx --from claude-gmail-mcp claude-gmail-mcp-auth <YOUR_PATH_TO_CREDENTIALS>Register the server with Claude Code (no env vars needed):
CLAUDE CODE — GMAIL API · TERMINAL
claude mcp add gmail --scope user -- uvx claude-gmail-mcpClaude Code — app password
CLAUDE CODE — APP PASSWORD · TERMINAL
claude mcp add gmail --scope user -e GMAIL_ADDRESS=<YOUR_GMAIL_ADDRESS> -e GMAIL_APP_PASSWORD=<YOUR_GMAIL_APP_PASSWORD> -- uvx claude-gmail-mcp<YOUR_GMAIL_ADDRESS> and <YOUR_GMAIL_APP_PASSWORD> are your address and a Gmail app password (https://myaccount.google.com/apppasswords).
