# @franciscpd/gmail-mcp-server

[![CI](https://github.com/franciscpd/mcp-server-gmail/actions/workflows/ci.yml/badge.svg)](https://github.com/franciscpd/mcp-server-gmail/actions/workflows/ci.yml)
[![npm version](https://img.shields.io/npm/v/@franciscpd/gmail-mcp-server)](https://www.npmjs.com/package/@franciscpd/gmail-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for Gmail. Read, search, send, reply, forward emails and manage labels — powered by 3 environment variables.

## Quick Start

```bash
npx -y @franciscpd/gmail-mcp-server
```

Set these environment variables:

| Variable | Description |
|----------|-------------|
| `GMAIL_CLIENT_ID` | OAuth2 client ID from Google Cloud Console |
| `GMAIL_CLIENT_SECRET` | OAuth2 client secret |
| `GMAIL_REFRESH_TOKEN` | OAuth2 refresh token (see [Setup Guide](#setup-guide)) |

## Setup Guide

### 1. Create a Google Cloud Project

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project (or select an existing one)
3. Note your project name for the next steps

### 2. Enable the Gmail API

1. Navigate to **APIs & Services** → **Library**
2. Search for "Gmail API"
3. Click **Enable**

### 3. Create OAuth2 Credentials

1. Navigate to **APIs & Services** → **Credentials**
2. Click **Create Credentials** → **OAuth client ID**
3. If prompted, configure the **OAuth consent screen**:
   - User type: **External** (or Internal for Workspace)
   - Add the scope: `https://mail.google.com/`
   - Add your email as a test user
4. Application type: **Web application**
5. Add `https://developers.google.com/oauthplayground` as an authorized redirect URI
6. Save your **Client ID** and **Client Secret**

### 4. Get a Refresh Token

1. Go to [Google OAuth2 Playground](https://developers.google.com/oauthplayground)
2. Click the ⚙️ gear icon (top right) and check **Use your own OAuth credentials**
3. Enter your **Client ID** and **Client Secret**
4. In the left panel, find **Gmail API v1** and select `https://mail.google.com/`
5. Click **Authorize APIs** and grant access
6. Click **Exchange authorization code for tokens**
7. Copy the **Refresh token**

## Configuration

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": ["-y", "@franciscpd/gmail-mcp-server"],
      "env": {
        "GMAIL_CLIENT_ID": "your-client-id",
        "GMAIL_CLIENT_SECRET": "your-client-secret",
        "GMAIL_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}
```

### Cursor

Add to your Cursor MCP settings:

```json
{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": ["-y", "@franciscpd/gmail-mcp-server"],
      "env": {
        "GMAIL_CLIENT_ID": "your-client-id",
        "GMAIL_CLIENT_SECRET": "your-client-secret",
        "GMAIL_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}
```

### Generic MCP Client

```bash
GMAIL_CLIENT_ID=your-client-id \
GMAIL_CLIENT_SECRET=your-client-secret \
GMAIL_REFRESH_TOKEN=your-refresh-token \
npx -y @franciscpd/gmail-mcp-server
```

The server communicates over **stdio** using the MCP protocol.

## Tools

| Tool | Description |
|------|-------------|
| `gmail_read_emails` | List emails from a label with pagination |
| `gmail_get_email` | Get full email content by ID |
| `gmail_search_emails` | Search with Gmail query syntax |
| `gmail_get_thread` | Get all messages in a thread |
| `gmail_get_attachment` | Download attachment by ID |
| `gmail_send_email` | Compose and send a new email |
| `gmail_reply_email` | Reply to an email in-thread |
| `gmail_forward_email` | Forward an email to new recipients |
| `gmail_list_labels` | List all labels with counts |
| `gmail_modify_labels` | Batch add/remove labels |

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Start the server
npm start
```

## License

MIT