A1 AI engineering company GitHub
Connect the Gmail MCP server to your AI agent Open source, MIT, on npm. Setup instructions for Claude, Cursor and Codex are in the repository; adoption questions — Telegram. GitHub repository Telegram

Gmail: Search and list messages — MCP tool

Gmail MCP tool: Searches the mailbox with Gmail query syntax and returns one triage-ready summary per message.

Technical name: list_messages

What task it solves

I want to find the messages that match a search.

Finds messages by any combination of Gmail search operators and labels, so the follow-up work (reading, replying, labelling) starts from the right set.

When to use it

Use it whenever the starting point is "which emails…": unread mail, everything from a sender, invoices with attachments from last week. If the unit of work is a whole conversation, prefer list_threads.

What to provide

  • query — optional. Gmail query syntax, the same operators as the Gmail search box: from:amy@example.com is:unread newer_than:7d has:attachment subject:invoice.
  • label_ids — optional. Only messages carrying ALL of these label ids (see list_labels).
  • page_size — optional. 1..100, default 25 (each summary costs one metadata read).
  • page_token — optional. nextPageToken from the previous page.
  • include_spam_trash — optional. Also search SPAM and TRASH (default false).
  • include_metadata — optional. false returns bare ids only — the cheapest form.

What it returns

messages[] with id, threadId, labelIds, snippet, from, to, subject, date and internalDate, plus nextPageToken and resultSizeEstimate (an estimate, not an exact count).

What changes in Gmail

Nothing. This is a pure read; it does not even mark anything as read.

Example request

Find unread emails from the last three days that have attachments, and show who sent them.

Errors and limitations

The API's search is the only filter; there is no server-side sort. resultSizeEstimate can be off — paginate to the end when an exact count matters. Each summary is one extra metadata read against the per-user quota (~250 units/s; a metadata get costs 5); the reads are throttled to a few in parallel so a full page of 100 does not burst the quota. A message deleted (by another client) between the search and its metadata read is skipped, so a page can contain slightly fewer summaries than page_size. Access also depends on token permissions, quotas, and upstream API limits.

Related MCP tools

Technical details