npm package: @iflow-mcp/j3k0-mcp-gmail
Description: Google Suite server for Model Context Protocol
Latest version: 1.0.1

# MCP Google Workspace Server

A Model Context Protocol server for Google Workspace services. This server provides tools to interact with Gmail and Google Calendar through the MCP protocol.

## Features

- **Multiple Google Account Support**
  - Use and switch between multiple Google accounts
  - Each account can have custom metadata and descriptions

- **Gmail Integration**
  - Query emails with advanced search
  - Read full email content and attachments
  - Create and manage drafts
  - Reply to emails
  - Archive emails
  - Handle attachments
  - Bulk operations support

- **Calendar Integration**
  - List available calendars
  - View calendar events
  - Create new events
  - Delete events
  - Support for multiple calendars
  - Custom timezone support

## Example Prompts

Try these example prompts with your AI assistant:

### Gmail
- "Retrieve my latest unread messages"
- "Search my emails from the Scrum Master"
- "Retrieve all emails from accounting"
- "Take the email about ABC and summarize it"
- "Write a nice response to Alice's last email and upload a draft"
- "Reply to Bob's email with a Thank you note. Store it as draft"

### Calendar
- "What do I have on my agenda tomorrow?"
- "Check my private account's Family agenda for next week"
- "I need to plan an event with Tim for 2hrs next week. Suggest some time slots"

## Prerequisites

- Node.js >= 18
- A Google Cloud project with Gmail and Calendar APIs enabled
- OAuth 2.0 credentials for Google APIs

## Installation

1. Clone the repository:
   ```bash
   git clone https://github.com/j3k0/mcp-google-workspace.git
   cd mcp-google-workspace
   ```

2. Install dependencies:
   ```bash
   npm install
   ```

3. Build the TypeScript code:
   ```bash
   npm run build
   ```

## Configuration

### OAuth 2.0 Setup

Google Workspace (G Suite) APIs require OAuth2 authorization. Follow these steps to set up authentication:

1. Create OAuth2 Credentials:
   - Go to the [Google Cloud Console](https://console.cloud.google.com/)
   - Create a new project or select an existing one
   - Enable the Gmail API and Google Calendar API for your project
   - Go to "Credentials" → "Create Credentials" → "OAuth client ID"
   - Select "Desktop app" or "Web application" as the application type
   - Configure the OAuth consent screen with required information
   - Add authorized redirect URIs (include `http://localhost:4100/code` for local development)

2. Required OAuth2 Scopes:
   ```json
   [
     "openid",
     "https://mail.google.com/",
     "https://www.googleapis.com/auth/calendar",
     "https://www.googleapis.com/auth/userinfo.email"
   ]
   ```

3. Create a `.gauth.json` file in the project root with your Google OAuth 2.0 credentials:
   ```json
   {
     "installed": {
       "client_id": "your_client_id",
       "project_id": "your_project_id",
       "auth_uri": "https://accounts.google.com/o/oauth2/auth",
       "token_uri": "https://oauth2.googleapis.com/token",
       "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
       "client_secret": "your_client_secret",
       "redirect_uris": ["http://localhost:4100/code"]
     }
   }
   ```

4. Create a `.accounts.json` file to specify which Google accounts can use the server:
   ```json
   {
     "accounts": [
       {
         "email": "your.email@gmail.com",
         "account_type": "personal",
         "extra_info": "Primary account with Family Calendar"
       }
     ]
   }
   ```

   You can specify multiple accounts. Make sure they have access in your Google Auth app. The `extra_info` field is especially useful as you can add information here that you want to tell the AI about the account (e.g., whether it has a specific calendar).

### Claude Desktop Configuration

Configure Claude Desktop to use the mcp-google-workspace server:

On MacOS: Edit `~/Library/Application\ Support/Claude/claude_desktop_config.json`

On Windows: Edit `%APPDATA%/Claude/claude_desktop_config.json`

<details>
  <summary>Development/Unpublished Servers Configuration</summary>
  
```json
{
  "mcpServers": {
    "mcp-google-workspace": {
      "command": "<dir_to>/mcp-google-workspace/launch"
    }
  }
}
```
</details>

<details>
  <summary>Published Servers Configuration</summary>
  
```json
{
  "mcpServers": {
    "mcp-google-workspace": {
      "command": "npx",
      "args": [
        "mcp-google-workspace"
      ]
    }
  }
}
```
</details>

## Usage

1. Start the server:
   ```bash
   npm start
   ```

   Optional arguments:
   - `--gauth-file`: Path to the OAuth2 credentials file (default: ./.gauth.json)
   - `--accounts-file`: Path to the accounts configuration file (default: ./.accounts.json)
   - `--credentials-dir`: Directory to store OAuth credentials (default: current directory)

2. The server will start and listen for MCP commands via stdin/stdout.

3. On first run for each account, it will:
   - Open a browser window for OAuth2 authentication
   - Listen on port 4100 for the OAuth2 callback
   - Store the credentials for future use in a file named `.oauth2.{email}.json`

## Available Tools

### Account Management

1. `gmail_list_accounts` / `calendar_list_accounts`
   - List all configured Google accounts
   - View account metadata and descriptions
   - No user_id required

### Gmail Tools

1. `gmail_query_emails`
   - Search emails with Gmail's query syntax (e.g., 'is:unread', 'from:example@gmail.com', 'newer_than:2d', 'has:attachment')
   - Returns emails in reverse chronological order
   - Includes metadata and content summary

2. `gmail_get_email`
   - Retrieve complete email content by ID
   - Includes full message body and attachment info

3. `gmail_bulk_get_emails`
   - Retrieve multiple emails by ID in a single request
   - Efficient for batch processing

4. `gmail_create_draft`
   - Create new email drafts
   - Support for CC recipients

5. `gmail_delete_draft`
   - Delete draft emails by ID

6. `gmail_reply`
   - Reply to existing emails
   - Option to send immediately or save as draft
   - Support for "Reply All" via CC

7. `gmail_get_attachment`
   - Download email attachments
   - Save to disk or return as embedded resource

8. `gmail_bulk_save_attachments`
   - Save multiple attachments in a single operation

9. `gmail_archive` / `gmail_bulk_archive`
   - Move emails out of inbox
   - Support for individual or bulk operations

### Calendar Tools

1. `calendar_list`
   - List all accessible calendars
   - Includes calendar metadata, access roles, and timezone information

2. `calendar_get_events`
   - Retrieve events in a date range
   - Support for multiple calendars
   - Filter options (deleted events, max results)
   - Timezone customization

3. `calendar_create_event`
   - Create new calendar events
   - Support for attendees and notifications
   - Location and description fields
   - Timezone handling

4. `calendar_delete_event`
   - Delete events by ID
   - Option for cancellation notifications

## Development

- Source code is in TypeScript under the `src/` directory
- Build output goes to `dist/` directory
- Uses ES modules for better modularity
- Follows Google API best practices

### Project Structure

```
mcp-google-workspace/
├── src/
│   ├── server.ts           # Main server implementation
│   ├── services/
│   │   └── gauth.ts        # Google authentication service
│   ├── tools/
│   │   ├── gmail.ts        # Gmail tools implementation
│   │   └── calendar.ts     # Calendar tools implementation
│   └── types/
│       └── tool-handler.ts # Common types and interfaces
├── .gauth.json             # OAuth2 credentials
├── .accounts.json          # Account configuration
├── package.json            # Project dependencies
└── tsconfig.json           # TypeScript configuration
```

### Development Commands

- `npm run build`: Build TypeScript code
- `npm start`: Start the server
- `npm run dev`: Start in development mode with auto-reload

## Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

## License

MIT License - see LICENSE file for details