# Gmail MCP Server

A Model Context Protocol (MCP) server that provides tools for interacting with Gmail through the Gmail API.

## Features

- 🔐 **OAuth2 Authentication** - Secure authentication with Google's OAuth2
- 📧 **Read Emails** - List and read emails from your Gmail inbox
- ✉️ **Send Emails** - Send emails through Gmail
- 🔍 **Search Emails** - Search emails using Gmail's powerful search syntax
- 📌 **Mark as Read/Unread** - Manage email read status
- 🛡️ **Secure** - Uses Google's official authentication flow

## Quick Start

1. **Install dependencies:**
   ```bash
   pip install -r requirements.txt
   ```

2. **Run the server:**
   ```bash
   python gmail_mcp_server.py
   ```

3. **First time setup:**
   - Use the `authenticate_gmail` tool to authorize access
   - This will open your browser for Google OAuth consent

## Available Tools

### `authenticate_gmail`
Authenticate with Gmail API using OAuth2. **Must be run first.**

### `list_emails`
List emails from your Gmail inbox.
- `max_results` (optional): Maximum number of emails to return (default: 10)
- `query` (optional): Gmail search query

### `read_email`
Read a specific email by its ID.
- `email_id` (required): The ID of the email to read

### `send_email`
Send an email through Gmail.
- `to` (required): Recipient email address
- `subject` (required): Email subject
- `body` (required): Email body (plain text)
- `cc` (optional): CC email addresses (comma-separated)
- `bcc` (optional): BCC email addresses (comma-separated)

### `search_emails`
Search emails using Gmail search syntax.
- `query` (required): Gmail search query
- `max_results` (optional): Maximum number of results (default: 10)

### `mark_as_read` / `mark_as_unread`
Mark an email as read or unread.
- `email_id` (required): The ID of the email to modify

## Gmail Search Syntax

- `is:unread` - Unread emails
- `from:example@gmail.com` - Emails from specific sender
- `subject:important` - Emails with "important" in subject
- `has:attachment` - Emails with attachments
- `after:2024/01/01` - Emails after specific date

## Configuration

- **Credentials file:** `gcp-oauth.keys.json` (your GCP OAuth credentials - see `gcp-oauth.keys.json.example`)
- **Token file:** `token.pickle` (created automatically after authentication)
- **MCP config:** `mcp_config.json` (for MCP client configuration)

### Setup Credentials

1. Copy `gcp-oauth.keys.json.example` to `gcp-oauth.keys.json`
2. Replace the placeholder values with your actual GCP OAuth credentials
3. Ensure Gmail API is enabled in your Google Cloud project

## Integration

To integrate this server with other projects:

1. **Copy the core files:**
   - `gmail_mcp_server.py` - Main server
   - `requirements.txt` - Dependencies
   - `gcp-oauth.keys.json` - Your OAuth credentials

2. **Install dependencies:**
   ```bash
   pip install -r requirements.txt
   ```

3. **Configure MCP client** using `mcp_config.json`:
   ```json
   {
     "mcpServers": {
       "gmail": {
         "command": "python",
         "args": ["gmail_mcp_server.py"],
         "cwd": "/path/to/your/gmail/mcp/server"
       }
     }
   }
   ```

## Testing

Run the included test to verify functionality:
```bash
python direct_test.py
```

This will test authentication, email listing, searching, and sending.

## Security

- OAuth2 credentials are stored securely using Google's official libraries
- Access tokens are refreshed automatically
- All API calls use HTTPS
- Keep `token.pickle` file secure

## License

This project is provided as-is for educational and integration purposes.