# Gmail MCP Server

This project provides a set of Gmail tools built with the **MCP (Model Context Protocol)** framework, allowing AI clients like Claude Desktop to send emails, create drafts, and read Gmail labels through Google's Gmail API. Tools are registered with `FastMCP` and can be tested via the MCP Inspector or connected directly to Claude Desktop.

## Features

- 📤 Send emails through Gmail
- 📝 Create email drafts
- 🏷️ Read Gmail labels

## Prerequisites

- Python 3.10+
- `uv` for dependency management
- MCP CLI (`mcp[cli]`)
- Gmail API credentials (`client_secret.json`)

## Enable Gmail API and Download Credentials

1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project (or use an existing one)
3. Enable the **Gmail API**
4. Configure the **OAuth consent screen** and add yourself as a **test user**
5. Create **OAuth 2.0 Client ID** credentials with application type **Desktop app**
6. Download the `client_secret.json` file and place it in the project root

## Setup

### 1. Clone the repository

```bash
git clone https://github.com/AsifMarwat/Gmail-mcp.git
cd Gmail-mcp
```

### 2. Install dependencies

```bash
uv sync
```

> **Note**: If you're not using `uv`, you can also run:
> ```bash
> pip install -r requirements.txt
> ```

### 3. Add your credentials

Place your downloaded `client_secret.json` in the project root. On first run, the app will open a browser window for you to sign in and authorize access — this generates a `token.json` file that stores your session so you don't need to log in again.

## Running the Project

### Development (MCP Inspector)

Use this to test your tools directly in the MCP Inspector:

```bash
uv run mcp dev main.py
```

### Connect to Claude Desktop

Add the server to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "gmail-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/Gmail-mcp",
        "run",
        "python",
        "main.py"
      ]
    }
  }
}
```

Restart Claude Desktop after saving. The Gmail tools will then be available directly in your conversations.

## Available Tools

| Tool | Description |
|------|-------------|
| `create_draft` | Creates a draft email in Gmail |
| `send_mail` | Sends an email directly from Gmail |
| `read_labels` | Reads all Gmail label information |

## Project Structure

```
.
├── main.py                # Script defining Gmail tools
├── client_secret.json     # OAuth credentials (keep private, not committed)
├── token.json             # Generated after first login (keep private, not committed)
├── pyproject.toml         # Project dependencies
├── uv.lock                # Locked dependency versions
└── README.md              # Project documentation
```

## Notes

- The script generates and uses `token.json` for storing OAuth tokens after your first authorization.
- **Do not commit `client_secret.json` or `token.json` to version control.** Both are excluded via `.gitignore`.
- This project was built as a learning exercise to understand how MCP servers integrate with the Gmail API and AI clients like Claude Desktop.