Gmail MCP Server
Provides tools for reading Gmail messages (list, search, read), creating drafts (when enabled), and sending emails (when enabled) via Gmail API with OAuth authentication.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Gmail MCP Server list my last 5 emails from inbox"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Gmail + SAP MCP Project — Phase 2: Gmail
Phase 2 keeps the Phase 1 MCP foundation and adds Gmail OAuth, read tools, draft creation, and guarded email sending. SAP is intentionally left for a later phase.
Available MCP tools
Foundation tools:
health_checkecho_textadd_numbers
Gmail tools:
gmail_auth_status— checks local OAuth setup without contacting Gmailgmail_get_profile— verifies the live API connectiongmail_list_messages— lists recent message summaries and message IDsgmail_search_messages— uses Gmail search syntaxgmail_read_message— reads one message using its message IDgmail_create_draft— creates a draft only when explicitly enabledgmail_send_email— sends email only when explicitly enabled
Draft creation and sending are disabled by default. This phase cannot delete, archive, label, or otherwise modify existing messages.
Related MCP server: Gmail MCP Server
1. Install or upgrade the project
Open Windows PowerShell in the extracted project folder:
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txtIf the virtual environment already exists, activate it and run only the final two commands.
Verify the project:
python -c "from mcp_server.server import mcp; print('MCP server import OK')"
pytest -q2. Create the Gmail OAuth application
Open Google Cloud Console and select or create a project.
Enable Gmail API for that project.
Open Google Auth Platform and configure the consent screen.
For a personal Gmail account, choose External and add your Gmail address as a test user while the application is in testing mode.
For a managed Google Workspace account, choose Internal only when the account and organization allow it.
Open Clients, select Create client, and choose Desktop app.
Download the client JSON.
Rename it to
credentials.jsonand place it here:
credentials/credentials.jsonDo not use a service-account key. Gmail user mailbox access in this project uses desktop OAuth consent.
3. Authorize your Gmail account
Stop MCP Inspector before authentication, then run:
python scripts\gmail_auth.pyYour browser will open. Select the Gmail account, review the read and compose access, and approve it. The script creates:
credentials/token.jsonBoth OAuth files are ignored by Git. Never upload, commit, email, or share
either file—especially token.json, which grants mailbox access.
4. Start MCP Inspector
npx -y @modelcontextprotocol/inspector python -m mcp_server.serverIf you enter the connection manually:
Transport: STDIO
Command: python
Arguments: -m mcp_server.serverClick Connect, open Tools, and click List Tools.
5. Test Gmail tools in order
A. Authentication status
Run gmail_auth_status with no input.
Expected important fields:
{
"credentials_file_exists": true,
"token_file_exists": true,
"authenticated": true,
"required_scopes_present": true,
"draft_create_enabled": false,
"send_enabled": false
}B. Live Gmail profile
Run gmail_get_profile with no input. It should return your Gmail address and
mailbox totals. This is the first live Gmail API test.
C. List Inbox messages
Run gmail_list_messages with:
{
"max_results": 5,
"label_ids": ["INBOX"]
}Copy a returned message_id for the read-message test.
D. Search Gmail
Run gmail_search_messages with:
{
"query": "is:unread",
"max_results": 5
}Other useful searches:
from:sender@example.com
subject:invoice
has:attachment newer_than:30dE. Read one message
Run gmail_read_message with an ID returned by list or search:
{
"message_id": "PASTE_MESSAGE_ID_HERE"
}F. Create a draft
Copy the example configuration and enable draft creation:
Copy-Item .env.example .envEdit .env and change only this line:
ALLOW_GMAIL_DRAFT_CREATE=trueRestart Inspector, then run gmail_create_draft:
{
"to": "your-own-address@gmail.com",
"subject": "MCP draft test",
"body": "This message was created as a Gmail draft through MCP."
}Confirm the message exists in the Gmail Drafts folder.
G. Send an email
Sending is irreversible. Test with your own email address first. Edit .env:
ALLOW_GMAIL_SEND=trueRestart Inspector, then run gmail_send_email:
{
"to": "your-own-address@gmail.com",
"subject": "MCP send test",
"body": "This message was sent through the Gmail MCP tool."
}Optional cc and bcc fields accept one address or comma-separated addresses.
Repeated tool calls send repeated emails; this tool is not idempotent.
Troubleshooting
credentials.json not found
Confirm the file exists:
Test-Path .\credentials\credentials.jsonThe result must be True.
Google says the app is not verified or access is blocked
While the External app is in testing mode, add the Gmail account under Google Auth Platform Audience > Test users, then run authentication again.
Scope changed or token is invalid
This project now requires both gmail.readonly and gmail.compose. If the
token came from the earlier read-only version, stop Inspector, remove only the
local token, and authenticate again:
Remove-Item .\credentials\token.json
python scripts\gmail_auth.pyInspector does not show the new tools
Upgrade the editable project and restart Inspector:
pip install -r requirements.txt
npx -y @modelcontextprotocol/inspector python -m mcp_server.serverPhase 2 completion checklist
Gmail API is enabled
Desktop OAuth JSON is saved as
credentials/credentials.jsongmail_auth.pycreatescredentials/token.jsongmail_auth_statusreturnsauthenticated: truegmail_get_profilereturns the correct Gmail addressList and search tools return message IDs
Read-message returns the selected message
OAuth includes
gmail.readonlyandgmail.composeDraft creation works only after its flag is enabled
Sending is blocked until
ALLOW_GMAIL_SEND=trueA send test to your own address succeeds
After this checklist passes, we can move to the SAP connection phase.
Available Tools
10 toolsadd_numbersA
Add two numbers to verify typed numeric tool arguments.
Inputs: a (required), b (required). Returns: object
echo_textA
Echo non-empty text to verify argument handling and tool responses.
Inputs: text (required). Returns: object
gmail_auth_statusA
Check local Gmail OAuth credential and token readiness without a network call.
Inputs: no named parameters. Returns: object
gmail_create_draftC
Create a Gmail draft after explicit enablement in .env.
Inputs: to (required), body (required), subject (required), cc, +1 more. Returns: object
gmail_get_profileA
Verify the Gmail API connection and return mailbox totals.
Inputs: no named parameters. Returns: object
gmail_list_messagesC
List recent Gmail messages with IDs, sender, subject, date, and snippet.
Inputs: label_ids, max_results. Returns: object
gmail_read_messageA
Read a Gmail message using a message_id returned by list or search.
Inputs: message_id (required). Returns: object
gmail_search_messagesB
Search Gmail using Gmail search syntax such as from:, subject:, or is:unread.
Inputs: query (required), max_results. Returns: object
gmail_send_emailCDestructive
Send an email after explicit enablement in .env.
Inputs: to (required), body (required), subject (required), cc, +1 more. Returns: object
health_checkA
Verify that the MCP server is running and show integration status.
Inputs: no named parameters. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Gmail-specific tools have distinct purposes, but the inclusion of add_numbers and echo_text creates a confusing mix of unrelated functionalities, potentially causing an agent to select the wrong tool.
Most Gmail tools follow a gmail_verb_noun pattern, but health_check, add_numbers, and echo_text break this convention, leading to inconsistent naming.
With 10 tools, the count is reasonable for a Gmail integration, but the presence of two test tools inflates the count unnecessarily and feels out of place.
The tool surface lacks essential operations like deleting messages, managing labels, or updating drafts, leaving significant gaps for a comprehensive email workflow.
Maintenance
Related MCP Connectors
Give AI agents their own email inboxes: list, read and send mail via scoped, revocable OAuth grants.
Manage Gmail end-to-end: search, read, send, draft, label, and organize threads. Automate workflow…
Manage Gmail messages, threads, labels, drafts, and settings from your workflows. Send and organiz…
Permissioned access to Gmail, Drive and Calendar via the user's own Google account
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables interaction with Gmail through the Gmail API with OAuth2 authentication. Supports reading, sending, searching emails, and managing read status through natural language.-
- FlicenseNot gradedqualityNot gradedmaintenanceEnables interaction with Gmail through the Gmail API, allowing users to list, read, search emails, create and send drafts, and get email summaries through natural language commands with OAuth2 authentication.-
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage Gmail accounts through natural language for tasks like sending, reading, searching, and organizing emails. It supports advanced features including draft management, label operations, and batch actions via secure OAuth 2.0 authentication.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to manage Gmail emails, including sending, searching, and organizing with labels and attachments via OAuth2.28 npm2MIT