list-emailsLABSCO SUMMARY
Gmail search syntax, available to an agent that can then act on what it finds.
The useful part is that search-emails takes real Gmail queries rather than a reduced filter set, so anything you already know how to find in the web client is findable here — and get-email pulls the whole message once the search narrows it down.
What it is
A Gmail server over the Gmail API: list what is in the inbox, search it, open a single message, and read the label set.
What you get
- Recent inbox mail, filtered by sender or by label, with a result cap you set
- Search using Gmail's own syntax — from:, has:attachment and the rest work unchanged
- One message pulled in full by its ID
- The account's labels, so a filter can name the right one
Requirements
Your own Google Cloud project with the Gmail API enabled and OAuth desktop credentials saved to disk, then one browser sign-in that writes the credentials file. Bun is used to install and build.
Setup effort
Build from source — git clone https://github.com/acro5piano/yagms.git
USE CASES
01
Finding the thread that has the attachment you need
Search with the same query you would type in Gmail, then open the one message that matches.
02
Catching up on what arrived while you were away
List recent inbox mail, capped at a number you can actually read, and filter it down by sender.
03
Pulling everything from one correspondent
Filter the listing by sender address rather than scrolling, then read the messages that matter.
04
Working with your own label scheme
Read back the label list first so a follow-up query filters on the label that actually exists.
4 tools
Listed in project docs. Your client may show a different list.
get-emailsearch-emailsget-labelsBEFORE YOU INSTALL
What to know first
Tools you get
4 tools named in the project's documentation.
Where it runs
The documented client runs the server on your machine.
INSTALLATION
Connect your client
You clone and build this one yourself.
Server setup
Create OAuth 2.0 credentials (Desktop application) for the Gmail API in Google Cloud Console, and save the downloaded JSON as ~/.yagms-oauth.keys.json
TERMINAL
git clone https://github.com/acro5piano/yagms.git
cd yagms
bun install
bun run build-gmail
bun run dist/gmail.js authMCP Clients
Any MCP client
ANY MCP CLIENT · JSON
{
"mcpServers": {
"gmail": {
"command": "bun",
"args": [
"run",
"<YOUR_PATH_TO_YAGMS>/dist/gmail.js"
],
"env": {},
"disabled": false,
"autoApprove": []
}
}
}
