# Gmail MCP Server

An MCP (Model Context Protocol) server that exposes Gmail inbox tools via Streamable HTTP transport. Connect your Gmail accounts to Claude Code and other MCP-compatible clients to search, read, organize, and compose emails.

## Features

- **Multi-account support** - Connect multiple Gmail accounts and switch between them
- **Full Gmail access** - Search messages, read threads, manage labels, archive, star, and compose drafts
- **Secure token storage** - Refresh tokens encrypted with AES-256-GCM in SQLite
- **Two-layer OAuth** - MCP-level JWT authentication plus Google OAuth for Gmail
- **Docker ready** - Run with Docker Compose for easy deployment

## Quick Start

### 1. Clone and install

```bash
git clone https://github.com/yourusername/gmail-mcp.git
cd gmail-mcp
npm install
```

### 2. Configure Google OAuth

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project or select an existing one
3. Enable the Gmail API
4. Create OAuth 2.0 credentials (Web application)
5. Set authorized redirect URI to `http://localhost:3000/oauth/callback`
6. Copy the Client ID and Client Secret

### 3. Set up environment

```bash
# Generate secure secrets
npm run setup:secrets

# Edit .env with your Google OAuth credentials
# Set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET
```

### 4. Build and run

```bash
npm run build
npm run start
```

The server runs on `http://localhost:3000`.

### 5. Connect to Claude Code

```bash
npm run claude:setup
```

This installs the MCP server connection and Gmail skills.

## Claude Code Integration

### Setup

After the server is running, install the Claude Code integration:

```bash
npm run claude:setup
```

This installs:
- MCP server connection to `~/.claude.json`
- 4 subagents to `~/.claude/agents/` (auto-triggered by context)
- 14 skills to `~/.claude/skills/` (explicit `/command`)

### Subagents (Auto-Triggered)

Subagents run automatically when Claude detects matching context. They operate in isolated context and return concise summaries.

| Subagent | Triggers on... |
|----------|----------------|
| `gmail-triage` | "prioritize my inbox", "what needs attention", "urgent emails" |
| `gmail-cleanup` | "clean up inbox", "what can I archive", "declutter" |
| `gmail-explore` | "analyze my inbox", "email patterns", "inbox overview" |
| `gmail-research` | "find emails about X", "summarize emails from Y" |

**Examples:**
```
> What needs my attention in email?
→ Auto-triggers gmail-triage subagent

> Find all emails about the project proposal
→ Auto-triggers gmail-research subagent
```

### Skills (Explicit Commands)

Skills run when you explicitly type `/command`. They run in your conversation context.

| Command | Description |
|---------|-------------|
| `/gmail-inbox` | Quick inbox status |
| `/gmail-unread` | List unread messages |
| `/gmail-starred` | View starred messages |
| `/gmail-labels` | View all labels |
| `/gmail-drafts` | View pending drafts |
| `/gmail-search` | Search with Gmail query syntax |
| `/gmail-thread` | View a conversation thread |
| `/gmail-compose` | Draft new emails |
| `/gmail-summarize` | Summarize email threads |
| `/gmail-triage` | Prioritize unread emails |
| `/gmail-cleanup` | Archive and organize inbox |
| `/gmail-explore` | Comprehensive inbox overview |
| `/gmail-connect` | Connect Gmail account |
| `/gmail-accounts` | View connected accounts |

### Management

```bash
npm run claude:status     # Check what's installed
npm run claude:uninstall  # Remove integration
```

## Configuration

Create a `.env` file based on `.env.example`:

| Variable | Description | Required |
|----------|-------------|----------|
| `PORT` | Server port (default: 3000) | No |
| `BASE_URL` | Public URL for OAuth callbacks | Yes |
| `GOOGLE_CLIENT_ID` | Google OAuth client ID | Yes |
| `GOOGLE_CLIENT_SECRET` | Google OAuth client secret | Yes |
| `OAUTH_REDIRECT_URI` | OAuth callback URL | Yes |
| `TOKEN_ENCRYPTION_KEY` | 32-byte base64 key for token encryption | Yes |
| `JWT_SECRET` | Secret for MCP JWT tokens | Yes |
| `DB_URL` | SQLite database path (default: `./data/gmail-mcp.db`) | No |
| `ALLOWED_ORIGINS` | Comma-separated CORS origins | No |

## Available Tools

### Authorization & Status
| Tool | Description |
|------|-------------|
| `gmail.status` | Check connection status and list connected accounts |
| `gmail.authorize` | Initiate OAuth flow to connect a Gmail account |

### Account Management
| Tool | Description |
|------|-------------|
| `gmail.listAccounts` | List all connected Gmail accounts |
| `gmail.setDefaultAccount` | Set the default account for operations |
| `gmail.removeAccount` | Disconnect a Gmail account |

### Reading Email
| Tool | Description |
|------|-------------|
| `gmail.searchMessages` | Search using Gmail query syntax |
| `gmail.batchSearchMessages` | Run multiple searches in parallel |
| `gmail.getMessage` | Get a single message by ID |
| `gmail.listThreads` | List conversation threads |
| `gmail.getThread` | Get all messages in a thread |
| `gmail.getAttachmentMetadata` | Get attachment info |

### Labels
| Tool | Description |
|------|-------------|
| `gmail.listLabels` | List all labels with counts |
| `gmail.getLabelInfo` | Get details about a specific label |
| `gmail.createLabel` | Create a custom label |
| `gmail.addLabels` | Add labels to messages/threads |
| `gmail.removeLabels` | Remove labels from messages/threads |

### Modifications
| Tool | Description |
|------|-------------|
| `gmail.archiveMessages` | Archive messages/threads |
| `gmail.unarchiveMessages` | Move back to inbox |
| `gmail.markAsRead` | Mark as read |
| `gmail.markAsUnread` | Mark as unread |
| `gmail.starMessages` | Add star |
| `gmail.unstarMessages` | Remove star |

### Drafts
| Tool | Description |
|------|-------------|
| `gmail.createDraft` | Create a new draft |
| `gmail.listDrafts` | List all drafts |
| `gmail.getDraft` | Get draft content |
| `gmail.updateDraft` | Update an existing draft |
| `gmail.deleteDraft` | Delete a draft |

## OAuth Scopes

Request only the scopes you need:

| Scope | Capabilities |
|-------|--------------|
| `gmail.readonly` | Search, read messages and threads |
| `gmail.labels` | Manage labels, archive, star, mark read/unread |
| `gmail.modify` | All of the above |
| `gmail.compose` | Create and manage drafts |

## Multi-Account Support

Connect multiple Gmail accounts per user:

```
// First account becomes the default
gmail.authorize → connects work@company.com (default)
gmail.authorize → connects personal@gmail.com

// Use specific account
gmail.searchMessages(query: "...", email: "personal@gmail.com")

// Or change the default
gmail.setDefaultAccount(email: "personal@gmail.com")
```

## Docker Deployment

```bash
# Build and start
docker compose up -d

# View logs
docker compose logs -f

# Stop
docker compose down
```

The SQLite database persists in `./data/`.

## Development

```bash
# Dev mode with hot reload
npm run dev

# Run tests
npm run test

# Type check
npm run typecheck

# Lint
npm run lint
```

## Architecture

```
MCP Client → Fastify HTTP (/mcp) → MCP Server → Gmail Client → Google APIs
                    ↓
            Token Store (SQLite) ← encrypted credentials
```

- **`src/index.ts`** - Entry point
- **`src/http/server.ts`** - Fastify server with `/mcp`, `/oauth/*`, `/healthz` endpoints
- **`src/mcp/server.ts`** - MCP server with 26 registered tools
- **`src/gmail/client.ts`** - Gmail API wrapper with token refresh
- **`src/auth/`** - MCP JWT auth and Google OAuth flows
- **`src/store/sqlite.ts`** - SQLite token store with AES-256-GCM encryption

## License

MIT