login_toolLABSCO SUMMARY
Sending is always two steps.
Drafting and sending are separate tools, so nothing leaves the account without a confirmation — worth knowing before you assume a reply went out. If you enable Calendar after having already authenticated for Gmail only, the existing token lacks the Calendar scopes: delete tokens.json, restart the server and authorise again. The project describes itself as a work in progress in beta.
What it is
A Gmail and Google Calendar server built around one idea: a reply should be drafted with the conversation history, the sender relationship and the entities in the message already loaded, rather than from the last message alone.
What you get
- Read and search:
get_email_overview,list_emails,get_email,search_emailsandget_email_count, using Gmail's own search syntax - Context-aware replies:
prepare_email_replygathers thread history and communication patterns first,send_email_replycreates the draft, andconfirm_send_emailis a separate step that actually sends it - Calendar:
create_calendar_eventtakes attendees, location and a colour by name or id,detect_events_from_emailpulls event details out of a message,list_calendar_eventsandsuggest_meeting_timeshandle the rest - Resources the client can read directly —
auth://status,gmail://status, plusemail://,thread://andsender://context for a specific id - Built-in guides as prompts: quickstart, authentication, Gmail search syntax, replies and debugging
- Authentication tools of its own:
authenticate,check_auth_status,login_tool,process_auth_code_toolandlogout
Requirements
Python 3.10+, and a Google Cloud project with the Gmail API enabled — the Calendar API too if you want the scheduling half. Create OAuth 2.0 credentials of type Desktop app and add your address as a test user on the consent screen. Install from a checkout with uv: uv venv, then uv pip install -e .. The client launches the project's main.py and supplies GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, CONFIG_FILE_PATH and PYTHONPATH; an optional TOKEN_ENCRYPTION_KEY encrypts the stored token. First use opens a browser to authorise and writes tokens.json.
Setup effort
Build from source — git clone https://github.com/bastienchabal/gmail-mcp.git
USE CASES
01
Replying to a long thread without rereading it
Gather the thread history and your past exchanges with the sender first, then draft from that context.
02
Turning a message into a calendar entry
Detect the date and time buried in the email and create the event, attendees included.
03
Finding a slot everyone can make
Read upcoming events and get suggested times inside a date range.
04
Digging something specific out of the archive
Search with Gmail's own syntax and open the message that matches.
17 tools
Listed in project docs. Your client may show a different list.
authenticateprocess_auth_code_toollogoutcheck_auth_statusget_email_countlist_emailsget_emailsearch_emailsget_email_overviewprepare_email_replysend_email_replyconfirm_send_emailcreate_calendar_eventdetect_events_from_emaillist_calendar_eventssuggest_meeting_timesBEFORE YOU INSTALL
What to know first
Tools you get
17 tools named in the project's documentation.
Requires
- Python 3.10+
- GOOGLE_CLIENT_ID in your environment
- GOOGLE_CLIENT_SECRET in your environment
Where it runs
The documented client runs the server on your machine.
INSTALLATION
Connect your client
You clone this one yourself.
Server setup
TERMINAL
git clone https://github.com/bastienchabal/gmail-mcp.git
cd gmail-mcp
pip install uv
uv venv
uv pip install -e .MCP Clients
Claude Desktop
CLAUDE DESKTOP · JSON
{
"mcpServers": {
"gmail-mcp": {
"command": "/<YOUR_ABSOLUTE_PATH>/gmail-mcp/.venv/bin/mcp",
"args": [
"run",
"/<YOUR_ABSOLUTE_PATH>/gmail-mcp/gmail_mcp/main.py:mcp"
],
"cwd": "/<YOUR_ABSOLUTE_PATH>/gmail-mcp",
"env": {
"PYTHONPATH": "/<YOUR_ABSOLUTE_PATH>/gmail-mcp",
"CONFIG_FILE_PATH": "/<YOUR_ABSOLUTE_PATH>/gmail-mcp/config.yaml",
"GOOGLE_CLIENT_ID": "<YOUR_GOOGLE_CLIENT_ID>",
"GOOGLE_CLIENT_SECRET": "<YOUR_GOOGLE_CLIENT_SECRET>",
"TOKEN_ENCRYPTION_KEY": "<YOUR_TOKEN_ENCRYPTION_KEY>"
}
}
}
}/<YOUR_ABSOLUTE_PATH> is the folder that contains your gmail-mcp clone, and <YOUR_GOOGLE_CLIENT_ID> and <YOUR_GOOGLE_CLIENT_SECRET> are the Desktop-app OAuth client you created in Google Cloud Console. TOKEN_ENCRYPTION_KEY is optional: generate one with python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())" or delete that line. The first request opens a browser to authorise Gmail and writes tokens.json.
