# Gmail MCP Server

A Model Context Protocol (MCP) server that provides read-only access to Gmail. Allows Claude Code to safely search, read, and analyze your Gmail inbox.

## Features

- **search_emails** - Search using Gmail query syntax
- **list_unread** - List unread emails
- **get_message** - Get full message content with attachments metadata
- **get_thread** - Get all messages in a conversation thread
- **draft_reply** - Prepare draft reply content (does NOT send)

## Prerequisites

- Node.js 18+
- A Google Cloud project with Gmail API enabled
- OAuth 2.0 Desktop App credentials

## Google Cloud Setup

### 1. Create a Google Cloud Project

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Click "Select a project" → "New Project"
3. Name your project (e.g., "Gmail MCP Server")
4. Click "Create"

### 2. Enable Gmail API

1. In your project, go to "APIs & Services" → "Library"
2. Search for "Gmail API"
3. Click on it and press "Enable"

### 3. Configure OAuth Consent Screen

1. Go to "APIs & Services" → "OAuth consent screen"
2. Select "External" (or "Internal" if using Google Workspace)
3. Fill in the required fields:
   - App name: "Gmail MCP Server"
   - User support email: your email
   - Developer contact: your email
4. Click "Save and Continue"
5. Add scopes:
   - `https://www.googleapis.com/auth/gmail.readonly`
   - `https://www.googleapis.com/auth/gmail.compose`
6. Add your email as a test user (if External)
7. Complete the setup

### 4. Create OAuth Credentials

1. Go to "APIs & Services" → "Credentials"
2. Click "Create Credentials" → "OAuth client ID"
3. Select "Desktop app" as application type
4. Name it (e.g., "Gmail MCP Desktop")
5. Click "Create"
6. Download or copy the Client ID and Client Secret

## Installation

```bash
# Clone or navigate to the project
cd gmail-mcp

# Install dependencies
npm install

# Build the project
npm run build
```

## Configuration

1. Copy the example environment file:

```bash
cp .env.example .env
```

2. Edit `.env` with your OAuth credentials:

```env
CLIENT_ID=your-client-id.apps.googleusercontent.com
CLIENT_SECRET=your-client-secret
```

## First Run (Authorization)

The first time you run the server, it will:

1. Open your browser for Google authorization
2. Ask you to sign in and grant permissions
3. Save the tokens locally in `token.json`

Subsequent runs will reuse the saved tokens automatically.

## Usage with Claude Code

### Add the MCP Server

```bash
claude mcp add gmail node ./dist/index.js
```

Or add to your Claude Code configuration manually:

```json
{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": ["./dist/index.js"],
      "cwd": "/path/to/gmail-mcp"
    }
  }
}
```

### Available Tools

#### search_emails

Search emails using Gmail query syntax.

```
Query examples:
- "from:user@example.com"
- "subject:meeting"
- "is:unread"
- "after:2024/01/01 before:2024/12/31"
- "has:attachment filename:pdf"
- "in:inbox -category:promotions"
```

#### list_unread

List unread emails (shortcut for `is:unread` search).

#### get_message

Get full content of a specific email by message ID.

#### get_thread

Get all messages in a conversation thread by thread ID.

#### draft_reply

Prepare a draft reply to a thread. Provides context for composing a response but does NOT send any email.

## Development

```bash
# Run in development mode (with hot reload)
npm run dev

# Type check
npm run typecheck

# Build for production
npm run build

# Run production build
npm start
```

## Security Notes

- OAuth tokens are stored locally in `token.json`
- Never commit `.env` or `token.json` to version control
- The server only requests read and compose permissions
- No emails are sent - draft_reply only prepares content
- Email content is not logged

## Troubleshooting

### "Missing CLIENT_ID or CLIENT_SECRET"

Ensure your `.env` file exists and contains valid credentials.

### "Authorization timeout"

The OAuth flow has a 5-minute timeout. Restart the server and complete authorization promptly.

### "Token refresh failed"

Delete `token.json` and re-authorize.

### "Access blocked: This app's request is invalid"

Ensure your OAuth consent screen is properly configured and your email is added as a test user.