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_check
• echo_text
• add_numbers

Gmail tools:

• gmail_auth_status — checks local OAuth setup without contacting Gmail
• gmail_get_profile — verifies the live API connection
• gmail_list_messages — lists recent message summaries and message IDs
• gmail_search_messages — uses Gmail search syntax
• gmail_read_message — reads one message using its message ID
• gmail_create_draft — creates a draft only when explicitly enabled
• gmail_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.

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.txt

If 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 -q

2. Create the Gmail OAuth application

1. Open Google Cloud Console and select or create a project.
2. Enable Gmail API for that project.
3. Open Google Auth Platform and configure the consent screen.
4. For a personal Gmail account, choose External and add your Gmail address as a test user while the application is in testing mode.
5. For a managed Google Workspace account, choose Internal only when the account and organization allow it.
6. Open Clients, select Create client, and choose Desktop app.
7. Download the client JSON.
8. Rename it to credentials.json and place it here:

credentials/credentials.json

Do 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.py

Your browser will open. Select the Gmail account, review the read and compose access, and approve it. The script creates:

credentials/token.json

Both 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.server

If you enter the connection manually:

Transport: STDIO
Command: python
Arguments: -m mcp_server.server

Click 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:30d

E. 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 .env

Edit .env and change only this line:

ALLOW_GMAIL_DRAFT_CREATE=true

Restart 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=true

Restart 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.json

The 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.py

Inspector 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.server

Phase 2 completion checklist

• [ ] Gmail API is enabled
• [ ] Desktop OAuth JSON is saved as credentials/credentials.json
• [ ] gmail_auth.py creates credentials/token.json
• [ ] gmail_auth_status returns authenticated: true
• [ ] gmail_get_profile returns the correct Gmail address
• [ ] List and search tools return message IDs
• [ ] Read-message returns the selected message
• [ ] OAuth includes gmail.readonly and gmail.compose
• [ ] Draft creation works only after its flag is enabled
• [ ] Sending is blocked until ALLOW_GMAIL_SEND=true
• [ ] A send test to your own address succeeds

After this checklist passes, we can move to the SAP connection phase.