# 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:

```powershell
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:

```powershell
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:

```text
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:

```powershell
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:

```text
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

```powershell
npx -y @modelcontextprotocol/inspector python -m mcp_server.server
```

If you enter the connection manually:

```text
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:

```json
{
  "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:

```json
{
  "max_results": 5,
  "label_ids": ["INBOX"]
}
```

Copy a returned `message_id` for the read-message test.

### D. Search Gmail

Run `gmail_search_messages` with:

```json
{
  "query": "is:unread",
  "max_results": 5
}
```

Other useful searches:

```text
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:

```json
{
  "message_id": "PASTE_MESSAGE_ID_HERE"
}
```

### F. Create a draft

Copy the example configuration and enable draft creation:

```powershell
Copy-Item .env.example .env
```

Edit `.env` and change only this line:

```text
ALLOW_GMAIL_DRAFT_CREATE=true
```

Restart Inspector, then run `gmail_create_draft`:

```json
{
  "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`:

```text
ALLOW_GMAIL_SEND=true
```

Restart Inspector, then run `gmail_send_email`:

```json
{
  "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:

```powershell
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:

```powershell
Remove-Item .\credentials\token.json
python scripts\gmail_auth.py
```

### Inspector does not show the new tools

Upgrade the editable project and restart Inspector:

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