google-mail
Provides read-only tools for interacting with Gmail through the Gmail API, exposed as typed client tasks, MCP tools, and FastAPI routes.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
xippios-google-mail
Typed Python client, MCP server and FastAPI routes for Gmail, part of the xippios SDK family. Names and semantics follow the upstream documentation; every response carries release metadata (source, endpoint, retrieved_at, published_at, vintage).
Install
uv add xippios-google-mail # client only
uv add "xippios-google-mail[mcp]" # + MCP server
uv add "xippios-google-mail[http]" # + FastAPI routerThe API takes an OAuth 2.0 bearer token, which the package renews in memory from a
refresh token per Gmail account and never writes to disk. The environment names the
operator's Desktop-app OAuth client, GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET, the
accounts, GOOGLE_ACCOUNTS (work,private), and one GOOGLE_<NAME>_REFRESH_TOKEN per
account (the test account demo is declared by GOOGLE_DEMO_REFRESH_TOKEN alone and
never listed). Every task takes the account's name first; list_accounts names the
declared ones.
A refresh token comes from the consent tool, which listens on http://127.0.0.1:<port>/,
prints the authorization URL to open in a browser signed in to the account, and prints the
refresh token once, to stdout; it stores nothing:
uvx --from xippios-google-mail xippios-google-mail-auth --account work # --scopes read: gmail.readonly
uvx --from xippios-google-mail xippios-google-mail-auth --account work --scopes write # gmail.modify, every read too
xippios-google-mail-auth --account work # the same, where xippios-google-mail is installedRelated MCP server: Yahoo Mail ChatGPT MCP
30-second example
from xippios.google.mail import tasks
tasks.list_accounts().data # ["work", "private"]
result = tasks.get_profile("work")
result.data.messages_total, result.meta.tenant, result.meta.retrieved_at
found = tasks.search_messages("work", "from:alice@example.com newer_than:7d", max_results=5)
[(row.from_, row.subject, row.date) for row in found.data]
message = tasks.get_message("work", found.data[0].id).data
message.headers, message.text, message.attachments # the decoded view; html on requestq is Gmail's own search syntax, sent as given. get_message returns a decoded view of
the message: its From, To, Cc, Bcc, Date, Subject, Message-ID, In-Reply-To and References
headers, the first plain-text part decoded, the first HTML part with include_html=True,
and its attachments' names, types and sizes, never their content. get_thread returns
the same view of each message in a thread, as text.
The write tasks, in xippios.google.mail.tasks_write (re-exported from
xippios.google.mail), need an account consented with --scopes write, and each
previews unless called with confirm=True:
from xippios.google.mail import tasks_write
preview = tasks_write.send_message("work", ["alice@example.com"], "Lunch on Friday", "See you!")
preview.data.headers, preview.data.body_lines # nothing was sent
sent = tasks_write.send_message(
"work", ["alice@example.com"], "Lunch on Friday", "See you!", confirm=True
)
sent.data.id, sent.data.label_ids # upstream's answer: ["SENT"], ...The read and write tasks are listed in the status table below.
MCP
{
"mcpServers": {
"google-mail": {
"command": "uvx",
"args": ["--from", "xippios-google-mail[mcp]", "xippios-google-mail-mcp-read"],
"env": {
"GOOGLE_CLIENT_ID": "<client id>.apps.googleusercontent.com",
"GOOGLE_CLIENT_SECRET": "<client secret>",
"GOOGLE_ACCOUNTS": "work,private",
"GOOGLE_WORK_REFRESH_TOKEN": "<refresh token>",
"GOOGLE_PRIVATE_REFRESH_TOKEN": "<refresh token>"
}
}
}
}The refresh tokens come from the consent tool above, one per account; a deployment that
serves one account can pass --account work in args and declare that account alone
("GOOGLE_ACCOUNTS": "work" and its token) instead of listing several.
The read server's tools are read-only and named google_mail_<verb>_<noun>. Results are capped, at
200 rows or 64 KB unless a tool has a cap of its own, with a note on how to see the rest.
google_mail_search_messages reads at most 50 messages a call (a list and one call per
message, 5 + 20 quota units each), and google_mail_get_thread reads a long thread in
parts with start and limit: a cut answer ends with where to resume, or says that the
message at its start alone passes the cap, which google_mail_get_message reads.
google_mail_get_message returns a message over the cap as its first 64 KB with a note:
include_html=False leaves the HTML out, and the rest is read in a mail client.
The server serves every declared account, and every tool but google_mail_list_accounts
takes account. --account <name> binds the server to one account: every tool acts on it,
takes no account and refuses a call that names one, and the server stops at startup
unless that account is declared with its refresh token. --http serves streamable HTTP instead of stdio, on a loopback --host only
(127.0.0.1, localhost, ::1): the server reaches every declared mailbox and carries no
authentication, so serving it beyond loopback takes --allow-remote and a gateway in front.
The write tools run in a server of their own, xippios-google-mail-mcp-write, so a
client of the read server never sees one; it takes --account too, and core holds it to
a loopback --host over --http unless --allow-remote is passed:
{
"mcpServers": {
"google-mail-write": {
"command": "uvx",
"args": ["--from", "xippios-google-mail[mcp]", "xippios-google-mail-mcp-write"],
"env": {
"GOOGLE_CLIENT_ID": "<client id>.apps.googleusercontent.com",
"GOOGLE_CLIENT_SECRET": "<client secret>",
"GOOGLE_ACCOUNTS": "work,private",
"GOOGLE_WORK_REFRESH_TOKEN": "<refresh token>",
"GOOGLE_PRIVATE_REFRESH_TOKEN": "<refresh token>"
}
}
}
}Its refresh tokens come from xippios-google-mail-auth --scopes write; a deployment that
only reads keeps the default read grant, which cannot change a mailbox.
Five write tools store a draft (google_mail_create_draft), delete one
(google_mail_delete_draft), send a message (google_mail_send_message), change a
message's labels (google_mail_modify_message) and move a message to the trash
(google_mail_trash_message). Every one returns a preview and changes nothing unless it
is called with confirm=true: a message's preview shows its To, Cc, Bcc, Subject,
In-Reply-To and References and the body's first 10 lines, the others name the draft or
the message and the labels. Confirmed, a tool returns Gmail's answer: the draft, or the
message with its labels; google_mail_delete_draft, which Gmail answers without a body,
returns the package's acknowledgement, {"performed": true, "id": "<the draft's id>"}.
A message is plain text in UTF-8, and Gmail sets From to the
account's address; a reply (in_reply_to_message_id) joins the original's conversation
and reads the original's headers first, its preview too. The write tools are no HTTP
routes.
Status
Upstream operation | Task function | MCP tool | Status |
none: the declared accounts |
|
| available; names only, no request |
|
|
| available; |
|
|
| available; the label ids |
|
|
| available; ids only, one page; |
|
|
| available; From, Subject, Date and snippet per message; |
|
|
| available; the decoded view: nine headers, the plain text, the HTML on request, the attachments' metadata (no content) |
|
|
| available; each message's decoded view, text only; |
|
|
| available; a preview unless |
|
|
| available; a preview unless |
|
|
| available; a preview unless |
|
|
| available; a preview unless |
|
|
| available; a preview unless |
Upstream terms and attribution
Data comes from Gmail (https://developers.google.com/workspace/gmail/api), on whatever terms upstream
states for it, if any; this package adds no rights to it. Documentation snapshot and its
attribution: docs/upstream/FETCHED.md.
Documents
sdk-core: docs/conventions.md — the conventions every xippios source package follows: its layout, names, results, tests and releases.
sdk-core: docs/adr.md — the index of the family's architecture decisions, which the conventions cite.
sdk-core: docs/definition-of-done.md — what a change satisfies before its pull request is opened.
sdk-core: docs/review-checklist.md — what the review of a pull request checks, in order.
sdk-google-mail: docs/adr.md — the index of this package's own decisions, generated from the records in
docs/adr/.sdk-google-mail: docs/upstream/FETCHED.md — the snapshot of the upstream documentation, the reference for names, parameters and semantics.
Licence
Apache-2.0. See LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Email: search, read, fetch attachments; attach files when the MCP client supports inputs.
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Your mailbox for MCP clients: search, read, draft, send, rules and notes. Sending is off by default.
Your own IMAP mailbox in any MCP client: search, read, flag, move; send and delete need confirm.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables MCP-compatible AI assistants to securely search multiple mailboxes, reconstruct email threads, and inspect attachments through read-only tools without altering mailbox state.Apache 2.0
- FlicenseNot gradedqualityBmaintenanceEnables read-only, sanitized access to Yahoo Mail through MCP, including email summaries, search, and folder listing.-
- AlicenseNot gradedqualityBmaintenanceEnables read-only Gmail access via MCP, allowing users to list and retrieve email messages with query and pagination support.4MIT
- AlicenseNot gradedqualityBmaintenanceEnables read-only IMAP email access through MCP, including listing accounts and folders, searching messages, retrieving message bodies and attachments, and viewing threads without modifying mail state.MIT