# gmail-mcp v1.0.0

Unified Multi-Account Google OAuth2 MCP Server for Gmail.
Search, read, compose, send, draft, and organize emails across multiple Google accounts seamlessly.

## Features (4 Unified Tools)

- **`gmail_search`**: Search emails with official Gmail search syntax (`is:unread`, `from:boss@corp.com`, `subject:invoice`, `newer_than:2d`, `has:attachment`)
- **`gmail_read`**: Read full email content and metadata (subject, sender, body text, HTML, CC, BCC, labels, attachment list)
- **`gmail_send`**: Send emails or create drafts (supports HTML, CC, BCC, thread replies, and file attachments)
- **`gmail_manage`**: Labeling, archiving, trash management, read/unread toggles, permanent deletion, and multi-account inventory

## Multi-Account Architecture

A single Google Cloud OAuth client (`credentials.json`) can authenticate multiple Gmail accounts.
Tokens are stored per-account in `~/.secrets/gmail/tokens/<account_name>.json`.

### 1. Setup Google OAuth Credentials (One-time)

1. Create a project in [Google Cloud Console](https://console.cloud.google.com/).
2. Enable the **Gmail API**.
3. Create an **OAuth 2.0 Client ID** (Desktop Application).
4. Download the client secret JSON file and save it as `~/.secrets/gmail/credentials.json` (or set `GMAIL_CREDENTIALS_JSON`).

### 2. Authenticate Accounts

Run the interactive authorization CLI for each account:

```bash
gmail-auth default    # Authenticates primary account
gmail-auth work       # Authenticates secondary work account
gmail-auth client_x   # Authenticates any additional account
```

List all authenticated accounts:
```bash
gmail-auth --list
```

## Installation in MCP Clients (Claude Desktop, OpenCode, Cursor, Windsurf)

### Option 1: Instant via `uvx` (Recommended)

```json
{
  "mcpServers": {
    "gmail": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/Steph-ux/gmail-mcp.git", "gmail-mcp"]
    }
  }
}
```

### Option 2: Via `pip install`

```bash
pip install git+https://github.com/Steph-ux/gmail-mcp.git
```

Then in your MCP config:
```json
{
  "mcpServers": {
    "gmail": {
      "command": "gmail-mcp"
    }
  }
}
```

### Option 3: Local Clone (Development)

```json
{
  "mcpServers": {
    "gmail": {
      "command": "python",
      "args": ["D:\\Steph\\script\\gmail-mcp\\server.py"]
    }
  }
}
```

## Usage Examples

### 1. Search Messages

```python
# Search in default account:
gmail_search(query='is:unread from:github')

# Search in work account:
gmail_search(account='work', query='subject:invoice newer_than:7d')
```

### 2. Read Message

```python
gmail_read(account='work', message_id='18f2a9b4c10d')
```

### 3. Send Email or Create Draft

```python
# Send direct email:
gmail_send(
    account='default',
    to='colleague@example.com',
    subject='Project Update',
    body_text='Here is the latest status...',
    body_html='<h1>Project Update</h1><p>Here is the latest status...</p>'
)

# Create a draft:
gmail_send(
    account='work',
    to='client@example.com',
    subject='Proposal draft',
    body_text='Please review the proposal.',
    draft=True
)
```

### 4. Organize & Manage

```python
# Archive email:
gmail_manage(account='work', action='archive', message_id='18f2a9b4c10d')

# Mark as unread:
gmail_manage(account='default', action='mark_unread', message_id='18f2a9b4c10d')

# Move to trash:
gmail_manage(account='default', action='trash', message_id='18f2a9b4c10d')

# List active accounts:
gmail_manage(action='list_accounts')
```

## Testing

```bash
pytest tests
```

## License

MIT