Skip to main content
Glama
Gmail MCP Server

Gmail MCP Server

by suryanandan1

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.

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

Available Tools

10 tools
add_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_emailC
Destructive

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

    C2.9/5.0

    Scored across 10 tools

    Disambiguation3/5

    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.

    Naming Consistency2/5

    Most Gmail tools follow a gmail_verb_noun pattern, but health_check, add_numbers, and echo_text break this convention, leading to inconsistent naming.

    Tool Count3/5

    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.

    Completeness2/5

    The tool surface lacks essential operations like deleting messages, managing labels, or updating drafts, leaving significant gaps for a comprehensive email workflow.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to manage Gmail emails, including sending, searching, and organizing with labels and attachments via OAuth2.
      28 npm
      2
      MIT